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Consul 简介 和 快速 入 门 


来 源 : vincentmi/consul-guide 
翻译 自 官 方 文档 . 
欢迎 进入 Consul 的 入 门 指南 ! 这 个 指南 是 开始 使 用 Consul 的 起 点 ,通过 这 个 指南 了 解 


Consul 是 什么 ,他 可 以 解决 哪些 问题 . 它 与 现 有 软件 的 比较 和 怎么 开始 使 用 它 . 如 果 你 
对 Consul 已 经 有 基本 的 了 解 ,可 以 阅读 文档 , 它 提供 更 多 可 用 特性 的 参考 . 


美文 原版 

https://www.consul.io/intro/ 

翻译 

工作 需要 看 了 下 ,顺便 翻译 了 。 翻 译 有 不 当 的 地 方 请 帮忙 指正 。 


Vincent Mi http:/vnzmi.com 
miwenshu#gmail.com 


Consul E 4t 2 


Consul 包 含 多 个 组 件 ,但 是 作为 一 个 整体 ,为 你 的 基础 设施 提供 服务 发 现 和 服务 配置 
的 工具 .他 提供 以 下 关键 特性 : 


e 服务 发 现 Consul 的 客户 端 可 用 提供 一 个 服务 ,比如 api 或 者 mysql ,另外 一 些 客 
户 端 可 用 使 用 Consul 去 发 现 一 个 指定 服务 的 提供 者 .通过 DNS 或 者 HTTP 应 用 程 
序 可 用 很 容易 的 找到 他 所 依赖 的 服务 . 


e 健康 检查 Consul 客 户 端 可 用 提供 任意 数量 的 健康 检查 ,指定 一 个 服务 ( 比 
如 :Webserver 是 否 返回 了 200 OK 状态 码 ) 或 者 使 用 本 地 节点 (比如 :内 存 使 用 是 
否 大 于 90%). 这 个 信息 可 由 operator 用 来 监视 集群 的 健康 .被 服务 发 现 组 件 用 来 
避免 将 流量 发 送 到 不 健康 的 主机 .. 


e Key/Value 存 储 应 用 程序 可 用 根据 自己 的 需要 使 用 Consul 的 层级 的 Key/Value 
存储 .比如 动态 配置 ,功能 标记 ,协调 ,领袖 选举 等 等 ,简单 的 HTTP API 让 他 更 易于 
使 用 . 


e 多 数据 中 心 : Consul 支 持 开 箱 即 用 的 多 数据 中 心 .这 意味 着 用 户 不 需要 担心 需要 
建立 额外 的 抽象 层 让 业务 扩展 到 多 个 区 域 . 


Consul 面 向 DevOps 和 应 用 开发 者 友好 .是 他 适合 现代 的 弹性 的 基础 设施 . 


基础 架构 


Consul 是 一 个 分 布 式 高 可 用 的 系统 . 这 节 将 包含 一 些 基础 ,我 们 忽略 掉 一 些 细节 这 样 
你 可 以 快速 了 解 Consul 是 如 何 工 作 的 .如 果 要 了 解 更 多 细节 ,请 参考 深入 的 架构 描述 . 


每 个 提供 服务 给 Consul 的 节点 都 运行 了 一 个 Consul agent. 发 现 服务 或 者 设置 和 获 
取 key/value 存 储 的 数据 不 是 必须 运行 agent. 这 个 agent 是 负责 对 节点 自身 和 节点 上 
的 服务 进行 健康 检查 的 . 


Agent 与 一 个 和 多 个 Consul Server 进行 交互 .Consul Server 用 于 存放 和 复制 数 
据 .server 自 行 选举 一 个 领袖 .虽然 Consul 可 以 运行 在 一 台 server , 但 是 建议 使 用 3 到 5 
台 来 避免 失败 情况 下 数据 的 丢失 .每 个 数据 中 心 建议 配置 一 个 server 集 群 . 


你 基础 设施 中 需要 发 现 其 他 服务 的 组 件 可 以 查询 任何 一 个 Consul 的 server 或 者 
agent.Agent 会 自动 转发 请 求 到 server . 


每 个 数据 中 运行 了 一 个 Consul server 集 群 . 当 一 个 跨 数 据 中 心 的 服务 发 现 和 配置 请 
求 创建 时 .本 地 Consul Server 转 发 请 求 到 远程 的 数据 中 心 并 返回 结果 . 


Consul 与 其 他 软件 的 比较 


https://www.consul.io/intro/vs/ 


使 用 Consul 


Consul 集 群 的 每 个 节点 都 必须 先 安装 Consul. 安 装 非常 容易 ,Consul 发 布 为 所 支持 的 
平台 和 架构 的 二 进 制 包 .这 个 指南 不 包含 从 源 代 码 编 译 Consul 的 内 容 . 


安装 Consudl 


安装 Consul, 找 到 适合 你 系统 的 包 下 载 他 .Consul 打 包 为 一 个 'Zip' 文 件 . 


下 载 后 解 开 压 缩 包 .拷贝 Consul 到 你 的 PATH 路 径 中 ,在 Unix 系 统 
中 ~/bin 和 /usr/local/bin 是 通常 的 安装 目录 .根据 你 是 想 为 单个 用 户 安装 还 
是 给 整个 系统 安装 来 选择 .在 Windows 系 统 中 有 可 以 安装 到 %PATH% 的 路 径 中 . 


OS X 


如 果 你 使 用 homebrew 作为 包 管 理 器 ,你 可 以 使 用 命令 


brew install consul 


完成 安装 后 ,通过 打开 一 个 新 终端 窗口 检查 consul 安装 是 否 成 功 .通过 执行 
consul 你 应 该 看 到 类 似 下 面 的 输出 


[root@hdp2 ~]# consul 
usage: consul [--version] [--help] <command> [<args>] 


Available commands are: 


agent Runs a Consul agent 

configtest Validate config file 

event Fire a new event 

exec Executes a command on Consul nodes 

force-leave Forces a member of the cluster to enter the " 
left" state 

info Provides debugging information for operators 

join Tell Consul agent to join cluster 

keygen Generates a new encryption key 

keyring Manages gossip layer encryption keys 

leave Gracefully leaves the Consul cluster and shut 
s down 

lock Execute a command holding a lock 

maint Controls node or service maintenance mode 

members Lists the members of a Consul cluster 

monitor Stream logs from a Consul agent 

reload Triggers the agent to reload configuration fi 
les 

rtt Estimates network round trip time between nod 
es 

version Prints the Consul version 

watch Watch for changes in Consul 


如 果 你 得 到 一 个 consul not be found 的 错误 ,你 的 PATH 可 能 没有 正确 设置 .请 
返回 检查 你 的 consul 的 安装 路 径 是 否 包含 在 PATH Y. 


运行 Agent 


完成 Consul 的 安装 后 ,必须 运行 agent. agent 可 以 运行 为 server 或 client 模 式 . 每 个 数据 
中 心 至 少 必 须 拥 有 一 台 server . 建议 在 一 个 集群 中 有 3 或 者 5 个 server. 部 署 单一 的 
server, 在 出 现 失败 时 会 不 可 避免 的 造成 数据 丢失 . 


其 他 的 agent 运 行为 client 模 式 .一 个 client 是 一 个 非常 轻 量 级 的 进程 .用 于 注册 服务 , 运 
行 健康 检查 和 转发 对 server 的 查询 .agent 必 须 在 集群 中 的 每 个 主机 上 运行 . 


查看 启动 数据 中 心 的 细节 请 查看 这 里 . 
启动 Agent 


为 了 更 简单 ,现在 我 们 将 启动 Consul agent 的 开发 模式 .这 个 模式 快速 和 简单 的 启动 
一 个 单 节点 的 Consul. 这 个 模式 不 能 用 于 生产 环境 ,因为 他 不 持久 化 任何 状态 . 


[root@hdp2 -]£ consu 
--» Starting Consul 
--» Starting Consul 


--» Consul agent run 
Node name: 
Datacenter: 
Server: 
Client Addr: 
RPC: 8400) 


Cluster Addr: 
Gossip encrypt: 
Atlas: 


l agent -dev 

agent... 

agent RPC... 

ning! 

'hdp2' 

'dc1' 

true (bootstrap: false) 

127.0.0.1 (HTTP: 8500, HTTPS: -1, DNS: 8600, 


10.0.0.52 (LAN: 8301, WAN: 8302) 
false, RPC-TLS: false, TLS-Incoming: false 
<disabled> 


==> Log data will now stream in as it occurs: 


2016/08/17 15:20 
0.52 
2016/08/17 15:20 
0.0.0.52 
2016/08/17 15:20 
lower] entering Foll 
2016/08/17 15:20 
ddr: 10.0.0.52:8300) 
2016/08/17 15:20 
1 (Addr: 10.0.0.52:8 
2016/08/17 15:20 
No cluster leader 
2016/08/17 15:20 
starting election 
2016/08/17 15:20 
didate] entering Can 
2016/08/17 15:20 
2016/08/17 15:20 
2:8300. Tally: 1 
2016/08/17 15:20 
2016/08/17 15:20 
der] entering Leader 


2016/08/17 15:20: 


(bootstrap) 
2016/08/17 15:20 
d peer set (2): [10. 
2016/08/17 15:20 
ed 
2016/08/17 15:20 
dex 2 
2016/08/17 15:20 
king health alive 
2016/08/17 15:20 
2016/08/17 15:20 


:41 [INFO] serf: EventMemberJoin: hdp2 10.0. 
:41 [INFO] serf: EventMemberJoin: hdp2.dc1i 1 


:41 [INFO] raft: Node at 10.0.0.52:8300 [Fol 

ower state 

:41 [INFO] consul: adding LAN server hdp2 (A 
(DC: dc1) 

:41 [INFO] consul: adding WAN server hdp2.dc 

300) (DC: dc1) 

:41 [ERR] agent: failed to sync remote state 


:42 [WARN] raft: Heartbeat timeout reached, 


:42 [INFO] raft: Node at 10.0.0.52:8300 [Can 
didate state 

:42 [DEBUG] raft: Votes needed: 1 

:42 [DEBUG] raft: Vote granted from 10.0.0.5 


:42 [INFO] raft: Election won. Tally: 1 

:42 [INFO] raft: Node at 10.0.0.52:8300 [Lea 
state 

42 [INFO] raft: Disabling EnableSingleNode 


:42 [DEBUG] raft: Node 10.0.0.52:8300 update 
0.0.52:8300] 

:42 [INFO] consul: cluster leadership acquir 
:42 [DEBUG] consul: reset tombstone GC to in 
:42 [INFO] consul: member 'hdp2' joined, mar 


:42 [INFO] consul: New leader elected: hdp2 
:43 [INFO] agent: Synced service 'consul' 


如 你 所 见 ,Consul Agent 启动 并 输出 了 一 些 日 志 数 据 .从 这 些 日 志 中 你 可 以 看 到 ,我 们 
的 agent 运 行 在 server 模 式 并 且 声 明 作为 一 个 集群 的 领袖 .额外 的 本 地 镀 锌 被 标记 为 
一 个 健康 的 成 员 . 


OS XJ] P ix xk: Consul 使 用 你 的 主机 hostname 作 为 默认 的 节点 名 字 . 如 果 你 的 
主机 名 包含 时 间 , 到 这 个 节点 的 DNS 查询 将 不 会 工作 .为 了 避免 这 个 情况 ,使 
用 -node 参数 来 明确 的 设置 node 名 . 


集群 成 员 


新 开 一 个 终端 窗口 运行 consul members ,你 可 以 看 到 Consul 集 群 的 成 员 . 下 一 节 
我 们 将 讲 到 加 入 集群 .现在 你 应 该 只 能 看 到 一 个 成 员 , 就 是 你 自己 : 


[root@hdp2 ~]# consul members 
Node Address Status Type Build Protocol DC 
hdp2 10.0.0.52:8301 alive server 0.6.4 2 dci 


这 个 输出 显示 我 们 自己 的 节点 .运行 的 地 址 ,健康 状态 ,自己 在 集群 中 的 角色 ,版 本 信息 . 
添加 -detailed 选项 可 以 查看 到 额外 的 信息 . 


members 命令 的 输出 是 基于 gossip 协 议 是 最 终 一 致 的 .意味 着 ,在 任何 时 候 ,通过 你 
本 地 agent 看 到 的 结果 可 能 不 是 准确 匹配 server 的 状态 .为 了 查看 到 一 致 的 信息 ,使 用 
HTTP API( 将 自动 转发 ) 到 Consul Server 上 去 进行 查询 : 


[root@hdp2 ~]# curl localhost:8500/vi/catalog/nodes 
[{"Node":"hdp2","Address":"10.0.0.52", "TaggedAddresses": {"wan":" 
10.0.0.52"}, "CreateIndex":3, "ModifyIndex": 4}] 


除了 HTTP API ,DNS 接口 也 可 以 用 来 查询 节点 .注意 ,你 必须 确定 将 你 的 DNS 查询 指 
向 Consul agent 的 DNS 服务 器 ,这 个 默认 运行 在 8600 端口 .DNS 条 目的 格式 ( 例 
如 :"Armons-MacBook-Air.node.consul") 将 在 后 面 讲 到 . 


$ dig @127.0.0.1 -p 8600 Armons-MacBook-Air.node.consul 


;; QUESTION SECTION: 
;Armons-MacBook-Air.node.consul. IN A 


;; ANSWER SECTION: 
Armons-MacBook-Air.node.consul. © IN A 172.20.20.11 


停止 Agent 


你 可 以 使 用 Ctrl-C 优雅 的 关闭 Agent. 中 断 Agent 之 后 你 可 以 看 到 他 离开 了 集群 并 关 
Hl. 

在 退出 中 ,Consul 提 醒 其 他 集群 成 员 ,这 个 节点 离开 了 .如 果 你 强行 杀 掉 进程 .集群 的 其 
他 成 员 应 该 能 检测 到 这 个 节点 失效 了 . 当 一 个 成 员 离 开 , 他 的 服务 和 检测 也 会 从 目录 
中 移 除 . 当 一 个 成 员 失效 了 ,他 的 健康 状况 被 简单 的 标记 为 危险 ,但 是 不 会 从 目录 中 移 
除 .Consul 会 自动 尝试 对 失效 的 节点 进行 重 连 .允许 他 从 某 些 网 络 条 件 下 恢复 过 来 . 离 
开 的 节点 则 不 会 再 继续 联系 . 


此 外 ,如 果 一 个 agent 作 为 一 个 服务 器 ,一 个 优雅 的 离开 是 很 重要 的 ,可 以 避免 引起 潜在 
的 可 用 性 故障 影响 达成 一 致 性 协议 ， 


查看 这 里 了 解 添加 和 移 除 server. 


注册 服务 

在 之 前 的 步骤 我 们 运行 了 第 一 个 agent. 看 到 了 集群 的 成 员 ,查询 节点 ,在 这 个 指南 我 们 
将 注册 我 们 的 第 一 个 服务 并 查询 这 些 服务 . 

定义 一 个 服务 

可 以 通过 提供 服务 定义 或 者 调用 HTTP API 来 注册 一 个 服务 .服务 定义 文件 是 注册 服 
务 的 最 通用 的 方式 .所 以 我 们 将 在 这 一 步 使 用 这 种 方式 .我 们 将 会 建立 在 前 一 步 我 们 
履 盖 的 代理 配置 。 

首先 ,为 Consul 配 置 创建 一 个 目录 .Consul 会 载 入 配置 文件 夹 里 的 所 有 配置 文件 .在 


Unix 系 统 中 通常 类 似 /etc/consul.d (.d 后 组 意思 是 这 个 路 径 包含 了 一 组 配置 文 
tt). 


$ sudo mkdir /etc/consul.d 


然后 ,我 们 将 编写 服务 定义 配置 文件 .假设 我 们 有 一 个 名 叫 web 的 服务 运行 在 8038 
口 .另外 ,我 们 将 给 他 设置 一 个 标签 .这 样 我 们 可 以 使 用 他 作为 额外 的 查询 方式 : 


echo '("service": {"name": "web", "tags": ["rails"], "port": 80} 


PON 
>/etc/consul.d/web.json 


现在 重启 agent , 设置 配置 目录 : 


$ consul agent -dev -config-dir /etc/consul.d 
--» Starting Consul agent... 


[INFO] agent: Synced service 'web' 


你 可 能 注意 到 了 输出 了 "synced" 了 web 这 个 服务 .意思 是 这 个 agent 从 配置 文件 中 载 
入 了 服务 定义 ,并 且 成 功 注册 到 服务 目录 . 


如 果 你 想 注 册 多 个 服务 ,你 应 该 在 Consul 配 置 目录 创建 多 个 服务 定义 文件 


查询 服务 


一 旦 agent 启 动 并 且 服 务 同步 了 .我 们 可 以 通过 DNS 或 者 HTTP 的 API 来 查询 服务 


DNS API 


让 我 们 首先 使 用 DNS API 来 查询 .在 DNS API 中 ,服务 的 DNS 名 字 是 
NAME.service.consul . 虽然 是 可 配置 的 ,但 默认 的 所 有 DNS 名 字 会 都 

在 consul 命名 空间 下 .这 个 子 域 告诉 Consul, 我 们 在 查询 服务 ，NAME 则 是 服务 的 

名 称 . 


对 于 我 们 上 面 注 册 的 Web 服 务 . 它 的 域名 是 web.service.consul 


[root@hdp2 consul.d]# dig 0127.0.0.1 -p 8600 web.service.consul 


; <<>> DiG 9.8.2rc1-RedHat-9.8.2-0.47.rc1.el6 <<>> @127.0.0.1 -p 
8600 web.service.consul 
(1 server found) 
; global options: +cmd 
; Got answer: 
; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 46501 
; flags: qr aa rd; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONA 
: 0 
; WARNING: recursion requested but not available 


(ee Ss Se ~ E Yep a 


;; QUESTION SECTION: 
;web.service.consul. IN A 


;; ANSWER SECTION: 
web.service.consul. 9 IN A 10.0 
.0.52 


;; Query time: 0 msec 

; SERVER: 127.0.0.1#8600(127.0.0.1) 
; WHEN: Wed Aug 17 19:07:05 2016 

;; MSG SIZE rcvd: 70 


如 你 所 见 ,一 个 A 记录 返回 了 一 个 可 用 的 服务 所 在 的 节点 的 上 地 址 . CA 记录 只 能 设 
置 为 IP 地 址 . 有 也 可 用 使 用 DNS API 来 接收 包含 地 址 和 端口 的 SRV 记 录 : 


[rootühdp2 ~]# dig @127.0.0.1 -p 8600 web.service.consul SRV 


; <<>> DiG 9.8.2rc1-RedHat-9.8.2-0.47.rc1.el6 <<>> @127.0.0.1 -p 
8600 web.service.consul SRV 

(1 server found) 

; global options: +cmd 

; Got answer: 

; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 33415 

; flags: qr aa rd; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONA 
1 

;; WARNING: recursion requested but not available 


;; QUESTION SECTION: 
;web.service.consul. IN SRV 


;; ANSWER SECTION: 
web.service.consul. 9 IN SRV 11 
80 hdp2.node.dci.consul. 


;; ADDITIONAL SECTION: 
hdp2.node.dci.consul. 0 IN A 10.0 
.0.52 


;; Query time: 1 msec 

;; SERVER: 127.0.0.148600(127.0.0.1) 
;; WHEN: Thu Aug 18 10:40:48 2016 

74 MSG SIZE rcvd: 130 


SRV 记录 告诉 我 们 web 这 个 服务 运行 于 节点 hdp2.node.dci.consul 
的 80 端口 .DNS 额外 返回 了 节点 的 A 记录. 


最 后 ,我 们 也 可 以 用 DNS API 通过 标签 来 过 滤 服 务 .基于 标签 的 服务 查询 格式 
为 TAG.NAME.service.consul .在 下 面 的 例子 中 ,我 们 请 求 Consul 返 回 有 
rails 标签 的 web 服务 .我 们 成 功 获 取 了 我 们 注册 为 这 个 标签 的 服务 


[rootühdp2 ~]# dig @127.0.0.1 -p 8600 rails.web.service.consul S 
RV 


; <<>> DiG 9.8.2rc1-RedHat-9.8.2-0.47.rc1.el6 <<>> @127.0.0.1 -p 
8600 rails.web.service.consul SRV 

(1 server found) 

; global options: +cmd 

; Got answer: 

; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 3517 

; flags: qr aa rd; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONA 
1 

;; WARNING: recursion requested but not available 


;, QUESTION SECTION: 
;rails.web.service.consul. IN SRV 


;; ANSWER SECTION: 
rails.web.service.consul. 0 IN SRV 1 1 80 
hdp2.node.dc1.consul. 


;, ADDITIONAL SECTION: 
hdp2.node.dc1.consul. 0 IN A 10.0 
.0.52 


;; Query time: 1 msec 

;; SERVER: 127.0.0.1#8600(127.0.0.1) 
;; WHEN: Thu Aug 18 11:26:17 2016 

;; MSG SIZE rcvd: 142 


HTTP API 


除了 DNS API 之 外 ,HTTP API 也 可 以 用 来 进行 服务 查询 : 


[root@hdp2 ~]# curl http://localhost:8500/v1/catalog/service/web 
[(" Node" : "hdp2", "Address":"10.0.0.52", "ServiceID":"web", "Service 
Name" :"web", "ServiceTags":["rails"], 'ServiceAddress":"", "Service 
Port":80, "ServiceEnableTagOverride": false, "CreateIndex":4, "Modif 
yIndex": 254} ] 


目录 API 给 出 所 有 节点 提供 的 服务 . 稍 后 我 们 会 像 通常 的 那样 带 上 健康 检查 进行 查询 . 
就 像 DNS 内 部 处 理 的 那样 .这 是 只 查看 健康 的 实例 的 查询 方法 : 


[root@hdp2 ~]# curl http://1localhost:8500/v1/catalog/service/web 
?passing 

[{"Node":"hdp2","Address":"10.0.0.52","ServiceID":"web","Service 
Name":"web","ServiceTags":["rails"],"ServiceAddress":"","Service 
Port":80, "ServiceEnableTagOverride": false, "CreateIndex":4, "Modif 


yIndex": 254} ] 


更 新 服务 


服务 定义 可 以 通过 配置 文件 并 发 送 SIGHUP 给 agent 来 进行 更 新 .这 样 你 可 以 让 你 在 
不 关闭 服务 或 者 保持 服务 请 求 可 用 的 情况 下 进行 更 新 . 


另外 HTTP API 可 以 用 来 动态 的 添加 , 移 除 和 修改 服务 . 


建立 集群 


我 们 开始 了 第 一 个 agent 并 且 在 agent 上 注册 并 查询 了 服务 .这 些 展示 了 Consul 是 如 何 
的 多 用 .但 是 我 们 还 不 知道 Consul 如 何 进行 扩 容 成 一 个 可 扩展 ,面向 生成 环境 的 服务 
发 现 架构 .这 一 章 我 们 将 创建 我 们 第 一 个 拥有 多 个 成 员 的 丨 正 的 集群 . 


当 一 个 agent 启 动 时 ,他 开始 不 知道 其 他 节点 的 信息 ,他 是 一 个 成 员 的 孤立 集群 .为 了 了 
解 其 他 集群 成 员 这 个 agent 必 须 加 入 一 个 已 经 存在 的 集群 .要 加 入 一 个 已 经 存在 的 集 
群 , 只 需要 知道 一 个 已 经 存在 的 集群 成 员 . 通 过 与 这 个 成 员 的 沟通 来 发 现 其 他 成 

员 ,Consul agent 可 以 加 入 任何 agent 而 不 只 是 出 于 server 模 式 的 agent. 


È 24 Agent 


官方 版 本 教程 里 使 用 了 Vagrant 来 启动 虚拟 机 .我 已 经 创建 了 多 个 虚拟 机 
因此 跳 过 这 部 分 


我 们 启动 了 另外 的 2 人 台 主 机 ,10.0.0.53 ,10.0.0.54 和 之 前 安装 的 方式 一 样 ,将 consul 找 
NZ) PATH 目录 完成 安装 . 


在 之 前 的 示例 中 ,我 们 使 用 了 -dev 参数 来 快速 的 创建 一 个 开发 模式 的 Server. 然 而 
这 并 不 能 充分 的 在 集群 环境 下 使 用 .现在 我 们 将 忽略 掉 -dev 标签 ,用 我 们 的 集群 选 
项 来 替换 他 . 


每 个 集群 中 的 节点 都 必须 要 一 个 唯一 的 名 字 .Consul 默 认 会 使 用 机 器 的 hostname. 我 
们 可 以 使 用 -node 手动 覆盖 他 . 


我 们 也 可 以 使 用 -bind 指 定 一 个 绑 定 的 地 址 让 Consul 在 这 个 地 址 上 进行 监听 ,这 个 地 
址 必须 可 以 被 其 他 集群 成 员 访 问 到 . 绑 定 地 址 不 是 必须 提供 ,Consuyl 选 择 第 一 个 私有 
IP 进 行 监听 ,不 过 最 好 还 是 指定 一 个 .生产 环境 的 服务 器 通常 有 多 个 网 络 接口 .所 以 指 
定 一 个 不 会 让 Consu| 绑 错 网 络 接口 . 


第 一 个 节点 将 扮演 集群 的 唯一 server 我们 使 用 -server 指定 他 ， 


-bootstrap-expect 选项 提示 Consul 我 们 期 待 加 入 的 Server 节 点 的 数量 .这 个 选 
项 的 作用 是 启动 时 推迟 日 志 复 制 直到 我 们 期 望 的 server 都 成 功 加 入 时 .你 可 以 阅读 户 
动 指南 了 解 更 多 . 


最 后 ,我 们 加 入 config-dir 选项 ,指定 服务 和 健康 检查 定义 文件 存放 的 路 径 . 
加 到 一 起 ,命令 如 下 : 


consul agent -server -bootstrap-expect 1 -data-dir /tmp/consul 
-node=hdp2 -bind=10.0.0.52 -config-dir /etc/consul.d 


现在 在 另外 一 个 终端 ,我 们 将 连接 第 二 个 节点 : 


ssh hdp3 
# 登录 第 二 台 机 器 


这 一 次 我 们 设置 绑 定 的 |P 地 址 为 第 二 个 节点 的 |P 的 地 址 ,并 指定 节点 名 称 . 因 为 这 个 
节点 将 不 是 Consule 的 server. 我 们 没有 打开 server 开关 .命令 如 下 : 


consul agent -data-dir /tmp/consul -node=hdp3 -bind-10.0.0.53 -c 
onfig-dir /etc/consul.d 


现在 ,你 有 运行 了 两 个 Consul 的 agent, 一 个 作为 server 另 一 个 作为 client. 这 两 个 agent 
还 互相 不 知道 对 方 , 只 是 作为 独立 的 单 节 点 集群 .为 了 验证 这 个 你 可 以 在 每 个 agent 运 
^f consul member ,只 能 看 到 各 自 自己 这 一 个 集群 成 员 . 


加 入 一 个 集群 
现在 我 们 告诉 第 一 个 agent 来 加 入 第 二 个 agent, 在 新 的 终端 运行 如 下 命令 


ssh hdp2 
consul join 10.0.0.53 
Successfully joined cluster by contacting 1 nodes. 


如 果 出 现 
Error joining the cluster: dial tcp 10.0.0.53:8301: getsockopt: n: 


可 能 是 业务 防火 墙 的 原因 ,检查 端口 8301 是 否 被 允许 


你 应 该 可 以 看 到 在 每 个 agent 的 日 志 输 出 窗口 的 一 些 输出 .如 果 你 仔细 阅读 会 发 现 .他 
们 收 到 了 加 入 信息 ,如 果 你 在 每 个 agent 运 行 consul members 你 会 看 到 类 似 下 面 的 
内 容 : 


[root@hdp2 ~]# consul members 


Node Address Status Type Build Protocol DC 
hdp2 10.0.0.52:8301 alive server 0.6.4 2 dci 
hdp3 10.0.0.53:8301 alive client 0.6.4 2 dci 


记 住 :为 了 加 入 集群 ,一 个 Consul 的 agent 只 需要 了 解 一 个 已 经 存在 的 集群 成 员 .加 
入 集群 后 agent 会 自动 交流 传递 完整 的 成 员 信息 . 


启动 时 自动 加 入 集群 


理想 的 情况 , 当 一 个 新 的 节点 在 数据 中 心 启动 时 ,他 应 该 自动 加 入 到 Consul 的 集群 中 ， 
而 不 需要 人 为 干预 .为 了 达到 这 个 效果 你 可 以 使 用 HashiCorp 的 Atlas 
和 -atlas-join 选项 .示例 如 下 : 


consul agent -atlas-join \ 
-atlas-ATLAS USERNAME/infrastructure \ 
-atlas-tokenz"YOUR ATLAS TOKEN" 


Atlas 的 用 户 名 和 token 可 以 通过 创建 Atlas 账 号 获取 .这 样 当 新 的 节点 启动 后 他 会 自动 
加 入 到 你 的 Consul 集 群 ,不 需要 硬 编码 配置 . 


另 一 种 选择 ,你 可 以 通过 -join 选项 和 start join 配置 将 其 他 已 知 的 agent 的 地 
址 进行 硬 编码 来 在 司 动 时 加 入 集群 . 


查询 节点 
就 像 查询 服务 一 样 .Consul 有 一 个 API 用 来 查询 节点 自己 .你 可 以 通过 DNS 和 HTTP 的 
API 来 进行 . 


DNS API 中 节点 名 称 结 构 为 NAME.node.consul 或 
者 NAME.node.DATACENTER.consul .如 果 数 据 中 心 名 字 省 略 ,Consul 只 会 查询 本 地 
数据 中 心 . 


例如 从 节点 hdp2 我 们 可 以 查询 节点 hdp3 的 地 址 


[root@hdp2 ~]# dig @127.0.0.1 -p 8600 hdp3.node.consul 


; <<>> DiG 9.8.2rc1-RedHat-9.8.2-0.47.rc1.el6 <<>> @127.0.0.1 -p 
8600 hdp3.node.consul 

; (1 server found) 

;; global options: +cmd 

;; Got answer: 

;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 5351 

;; flags: qr aa rd; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONA 
L: 0 

;; WARNING: recursion requested but not available 

;; QUESTION SECTION: 

;hdp3.node.consul. IN A 


;; ANSWER SECTION: 
hdp3.node.consul. 0 IN A 10.0 
.0.53 


;; Query time: 1 msec 

;; SERVER: 127.0.0.1#8600(127.0.0.1) 
;; WHEN: Thu Aug 18 14:32:02 2016 

;; MSG SIZE rcvd: 66 


除 服 务 之 外 查询 节点 的 能 力 对 于 系统 管理 任务 非常 重要 .例如 知道 节点 的 SSH 登 录 地 
址 ,可 以 简单 的 将 节点 加 入 到 Consul 集 群 并 查询 他 . 


离开 集群 


离开 集群 ,你 可 以 ctrl-c 优雅 的 退出 ,也 可 以 直接 Kil 掉 agent 进 程 .优雅 的 退出 可 以 
让 节点 转变 为 离开 状态 .否则 节点 将 被 标记 为 失败 .详细 的 细节 可 以 查看 过 里 . 


健康 检查 


我 们 现在 看 到 Consul 运 行 时 如 此 简单 .添加 节点 和 服务 ,查询 节点 和 服务 .在 这 一 节 . 我 
们 将 继续 添加 健康 检查 到 节点 和 服务 .健康 检查 是 服务 发 现 的 关键 组 件 .预防 使 用 到 
不 健康 的 服务 . 


这 一 步 建立 在 前 一 节 的 Consul 集 群 创建 之 上 .目前 你 应 该 有 一 个 包含 两 个 节点 的 
Consul 集 群 . 
定义 检查 


和 服务 类 似 , 一 个 检查 可 以 通过 检查 定义 或 HTTP API 请 求 来 注册 . 
我 们 将 使 用 和 检查 定义 来 注册 检查 .和 服务 类 似 ,因为 这 是 建立 检查 最 常用 的 方式 . 
在 第 二 个 节点 的 配置 目录 建立 两 个 定义 文件 : 


vagrant@n2:~$ echo '("check": {"name": "ping", 

"script": "ping -ci 163.com >/dev/null", "interval": "30s"}}' 
N 

>/etc/consul.d/ping.json 
vagrant@n2:~$ echo '{"service": {"name": "web", "tags": ["rails" 
la DoD BU 

"check": {"script": "curl localhost >/dev/null 2>&1", "interva 


MUS "10s"}}}' N 
>/etc/consul.d/web.json 


第 一 个 定义 增加 了 一 个 主机 级 别 的 检查 ,名 字 为 "ping" . 这 个 检查 每 30 秒 执行 一 次 , 执 
^f ping -c1 163.com .在 基于 脚本 的 健康 检查 中 ， 脚本 运行 在 与 Consul 进 程 一 样 
的 用 户 下 .如 果 这 个 命令 以 非 0 值 退 出 的 话 这 个 节点 就 会 被 标记 为 不 健康 .这 是 所 有 基 
于 脚本 的 健康 检查 的 约定 . 


第 二 个 命令 定义 了 名 为 web 的 服务 ,添加 了 一 个 检查 .每 十 分 钟 通过 curl 发 送 一 个 请 
求 ,确定 web 服 务 器 可 以 访问 .和 主机 级 别 的 检查 一 样 .如 果 脚 本 以 非 0 值 退出 则 标记 为 
不 健康 . 


现在 重启 第 二 个 agent 或 者 发 送 SIGHUP 信号 ,你 应 该 可 以 看 到 如 下 的 日 志 内 容 输 出 : 


==> Reloading configuration... 
2016/08/18 15:29:57 [INFO] agent: Synced service 'web' 
2016/08/18 15:29:57 [INFO] agent: Synced check 'ping' 
2016/08/18 15:29:58 [WARN] agent: Check 'service:web' is now 
critical 


前 几 行 检查 到 agent 同 步 了 新 的 定义 .最 后 一 行 检查 到 web 服务 出 于 危险 状态 .这 是 因 
为 我 们 实际 上 没有 运行 一 个 web 服 务 器 .所 以 “curl 的 测试 会 一 直 失 败 | 


检查 健康 状态 
现在 我 们 加 入 了 一 些 简 简 我 们 能 适应 HTTP 他 们 .首先 我 们 检查 有 
哪些 失败 的 检查 .使 用 这 个 命令 (注意 :这 个 命令 可 以 运行 在 任何 节点 ) 


[rootühdp3 consul.d]£ curl http://localhost:8500/vi/health/state 
/critical 

[{"Node":"hdp3", "CheckID":"service:web","Name":"Service 'web' ch 
eck", "Status" :"critical"," 'Notes":""," "Output": "", "ServiceID":"web 
", ServiceName":"web", "CreateIndex":878, "ModifyIndex":878} ] 


我 们 可 以 看 到 ,只 有 一 个 检查 我 们 的 web 服务 在 critical 状态 
另外 ,我 们 可 以 尝试 用 DNS 查询 web 服 务 ,Consul 将 不 会 返回 结果 .因为 服务 不 健康 . 


[root@hdp3 consul.d]# dig @127.0.0.1 -p 8600 web.service.consul 


; <<>> DiG 9.8.2rc1-RedHat-9.8.2-0.47.rc1.el6 <<>> @127.0.0.1 -p 
8600 web.service.consul 

; (1 server found) 

;; global options: +cmd 

;; Got answer: 

;; ->>HEADER<<- opcode: QUERY, status: NXDOMAIN, id: 33096 

;; flags: qr aa rd; QUERY: 1, ANSWER: 0, AUTHORITY: 1, ADDITIONA 
L: 0 

;; WARNING: recursion requested but not available 

;; QUESTION SECTION: 

;web.service.consul. IN A 


;, AUTHORITY SECTION: 
consul. 0 IN SOA ns.consul. p 
ostmaster.consul. 1471507354 3600 600 86400 0 


;; Query time: 8 msec 

;; SERVER: 127.0.0.148600(127.0.0.1) 
;; WHEN: Thu Aug 18 16:02:34 2016 

;; MSG SIZE rcvd: 104 


下 一 步 


在 本 章 , 你 学 到 了 如 何 鉴定 的 添加 健康 检查 .检查 定义 可 以 通过 配合 文件 并 发 
送 SIGHUP 到 agent 进 行 更 新 .另外 ,HTTP API 可 以 用 来 动态 添加 , 移 除 和 修改 检查 ,以 


及 进行 TTL 检 查 .TTL 可 以 让 应 用 程序 更 紧密 的 与 Consul 集 成 .将 检查 的 状态 加 入 到 业 
务 逻辑 的 计算 . 


键 值 数据 存储 


除了 提供 服务 发 现 和 健康 检查 的 集成 .Consul 提 供 了 一 个 多 用 的 键 / 值 存 储 .这 可 以 用 
来 保持 动态 配置 ,协助 服务 协调 ,领袖 选举 ,做 开发 者 可 以 想到 的 任何 事情 . 


这 一 


章 假设 你 已 经 有 至 少 一 个 Consul 的 agent 在 运行 . 


简单 使 用 


为 了 演示 如 果 简 单 的 使 用 键 值 存 储 .我 们 将 操作 一 些 键 .查询 本 地 agent 我 们 首先 确认 


现在 还 没有 存储 任何 key. 


[root@hdp3 consul.d]£ curl -v http://localhost:8500/v1i/kv/?recur 


se 


* 


* 


V M 


* +*#NANNANANAVVV 


为 没有 key 所 以 我 们 得 到 了 一 个 404 响 应 .现在 我 们 `PUT 一 些 示 例 的 Key: 


About to connect() to localhost port 8500 (#0) 


Trying ::1... 拒绝 连接 
Trying 127.0.0.1... connected 


Connected to localhost (127.0.0.1) port 8500 (#0) 


GET /vi/kv/?recurse HTTP/1.1 


User-Agent: curl/7.19.7 (x86 64-redhat-linux-gnu) libcurl/7.19 
.7 NSS/3.21 Basic ECC zlib/1.2.3 libidn/1.18 libssh2/1.4.2 


Host: localhost:8500 
Accept: */* 


HTTP/1.1 404 Not Found 

X-Consul-Index: 1 

X-Consul-Knownleader: true 
X-Consul-Lastcontact: 0 

Date: Thu, 18 Aug 2016 08:21:39 GMT 
Content-Length: 0 

Content-Type: text/plain; charset=utf-8 


Connection #0 to host localhost left intact 
Closing connection #0 


[root@hdp3 consul.d]£ curl -X PUT -d 'test' http://localhost:850 
0/vi/kv/web/key1 

[root@hdp3 consul.d]£ curl -X PUT -d 'test' http://localhost:850 
0/vi/kv/web/key2?flags=42 

[root@hdp3 consul.d]# curl -X PUT -d 'test' http://localhost:85 
00/v1/kv/web/sub/key3 

[root@hdp3 consul.d]£ curl http://localhost:8500/v1/kv/?recurse 
[{"LockIndex":0, "Key" :"web/key1", "Flags":0, "Value":"dGVzdA--", "C 
reateIndex":1201, "ModifyIndex":1201}, {"LockIndex":0, "Key": "web/k 
ey2","Flags":42, "Value": "dGVzdA==", "CreateIndex":1205, "ModifyInd 
ex":1206}, {"LockIndex":0, "Key": "web/sub/key3", "Flags":0, "Value": 
"dGVzdA==", "CreateIndex":1217, "ModifyIndex":1217}] 


我 们 创建 了 值 为 "test" 的 3 个 Key, 注 意 返回 的 值 是 经 过 了 base64 编 码 的 .用 来 支持 非 
UTF8 编 码 字符 .对 Key web/key2 我 们 设置 了 一 个 标志 值 为 42 .所 有 的 key 支 持 设 
置 一 个 64 位 的 整形 数字 标志 .Consul 内 部 不 适用 这 个 值 .但 是 他 可 以 被 客户 端 适用 来 
做 一 些 元 数据 . 


完成 设置 后 ,我 们 发 起 了 一 个 GET 请 求 来 接收 多 个 key 的 值 ,使 用 ?recurse ^ X. 
你 可 以 获取 单个 的 key 


[rootühdp3 consul.d]£ curl http://localhost:8500/v1/kv/web/key1 
[{"LockIndex":0, "Key" :"web/key1", "Flags":0, "Value" :"dGVzdA==", "C 
reateIndex":1201, "ModifyIndex":1201} ] 


删除 key 也 很 简单 .通过 DELETE 动作 来 完成 .我 们 可 以 通过 指定 完整 路 径 来 删除 一 个 
单独 的 key. 或 者 我 们 可 以 使 用 ?recurse 递归 的 删除 主 路 径 下 所 有 key. 


[root@hdp3 consul.d]£ curl -X DELETE http://localhost :8500/v1/kv 
/web/sub?recurse 

true 

[root@hdp3 consul.d]£ curl http://localhost:8500/vi/kv/web?recur 
se 

[{"LockIndex":0, "Key" :"web/key1", "Flags":0, "Value": "dGVzdA==", "C 
reateIndex":1201, "ModifyIndex":1201}, {"LockIndex":0, "Key": "web/k 
ey2","Flags":42, "Value": "dGVzdA==", "CreateIndex":1205, "ModifyInd 
ex":1206} ] 


可 以 通过 发 送 相 同 的 URL 并 提供 不 同 的 消息 体 的 PUT 请 求 去 修改 一 个 Key. 另 
外 ,Consul 提 供 一 个 检查 并 设置 的 操作 ,实现 原子 的 Key 修 改 .通过 ?cas= 参数 加 
上 GET 中 最 近 的 ModifyIndex 来 达到 .例如 我 们 想 修改 "web/key1": 


[root@hdp3 consul.d]# curl -X PUT -d 'newval' http://localhost:8 
500/vi/kv/web/key1?cas=1201 


true 
[root@hdp3 consul.d]# curl -X PUT -d 'newval' http://localhost:8 


500/vi/kv/web/key1?cas=1201 
false 


在 这 种 情况 下 ,第 一 次 CAS 更 新 成 功 因为 ModifyIndex 是 1201 .而 第 二 次 失败 
是 因为 ModifyIndex 在 第 一 次 更 新 后 已 经 不 是 1201 了 . 


我 们 也 可 以 使 用 ModifyIndex 来 等 待 key 值 的 改变 .例如 我 们 想 等 待 key2 被 修改 : 


[root@hdp3 consul.d]# curl http://localhost:8500/v1/kv/web/key2 
[{"LockIndex":0, "Key": "web/key2", "Flags":42, "Value":"dGVzdA-z"," 
CreateIndex":1205, "ModifyIndex":1206} ] 


[root@hdp3 consul.d]# curl "http://localhost:8500/v1/kv/web/key2 


?index=1206&wait=5s" 
[{"LockIndex":0, "Key": "web/key2", "Flags":42, "Value": "dGVzdA==", " 
CreateIndex":1205, "ModifyIndex":1206} ] 


通过 提供 ?index= ,我 们 请 求 等 待 key 值 有 一 个 比 1206 更 大 的 ModifyIndex . 虽 
然 ?wait=5s 参数 限制 了 这 个 请 求 最 多 5 秒 , 否 则 返回 当前 的 未 改变 的 值 . 这 样 可 以 
有 效 的 等 待 key 的 改变 .另外 ,这 个 功能 可 以 用 于 等 待 一 组 key. 直 到 其 中 的 某 个 key 有 

修改 


下 一 步 
这 里 有 一 些 说 API 可 以 支持 的 操作 的 例子 ,要 查看 完整 文档 .请 查看 这 里 . 
下 面 我 们 将 看 一 看 Consud| 支 持 的 WebUl 选 项 . 


WEBA i 


Consul 同 时 提供 了 一 个 漂亮 的 功能 齐全 的 WEB 规 面 , 开 箱 即 用 .界面 可 以 用 来 查看 所 
有 的 节点 ,可 以 查看 健康 检查 和 他 们 的 当前 状态 .可 以 读 取 和 设置 K/V 存储 的 数据 .UI 
自动 支持 多 数据 中 心 . 


运行 WebUI 有 两 个 选项 . 使 用 HashiCorp 提 供 的 Atlas 来 托管 你 的 仪表 瘟 或 者 使 用 
Consul 自 己 托管 的 开源 UI 


Atlas 托 管 的 仪表 部 


Q ATLAS 





®© hashicorp/consul-demo 





Ô Some problems detected in your infrastructure 
1 health r r 


A JT 7% E Consult A Atlasi da 4r o 2f ON EC ed i 的 配置 文件 :你 的 Atlas 名 称 
和 TOKEN. 下 面 是 一 个 命令 行 示例 用 来 配置 agent 的 这 些 设置 : 


$ consul agent -atlas-ATLAS USERNAME/demo -atlas-token="ATLAS_TO 
KEN" 


获取 Atlas 用 户 名 和 token, 创 建 一 个 账号 并 替换 成 你 自己 的 配置 .你 可 以 查看 线 
-EDemo. 


Consult € 96 & & 


WEB 管 理 界面 


Consul 





| > | [CS] | E] | + | GS demo.consul.io/ui/£/nyc1/nodes/nyc1-worker-3 





nyc1-worker-3 162.243.162.229 
Filter by name any status $ EXPAND 
B nyc1-server-1 1services SERVICES 
redis :6379 
g nyc1-server-2 1services 
n nyc1-server-3 1 service: s web 80 
8 nyc1-worker-1 2 services CHECKS 
E nyci-worker-2 2 services Ee 
Service 'redis' check service:redis passing 
nyc1-worker-3 2 services 
NOTES 
OUTPUT 


Service 'web' check service:web passing 
NOTES 
OUTPUT 


% Total  % Received % Xferd Average Speed Time 
Dload Upload Total Spent Left 


9 9 9 0 8 [E 
100 177 100 177 9 0 15511 @ -~: 一 


<htmL><body><hl>It works!«/hl» 
<p>This is the default web page for this server.</p> 


<p>The web server software is running but no content has been added, yet.</p> 
</body></htm1> 





设置 自 托管 的 UI 服务 ,启动 Consul 时 使 用 -ui 参数 : 


[root@hdp4 ~]# consul agent -ui 


UI 的 路 径 在 ui ,使 用 HTTP API 相同 的 端口 .默认 为 
http://localhost:8500/ui . 


> 
译 者 注 : -bind 指定 你 要 将 HTTP 绑 定 到 的 IP, 绑 定 到 一 个 公 网 IP 一 边 可 以 从 外 


部 访问 ,否则 只 能 在 本 机 进行 访问 .所 以 我 的 启动 命令 是 
[root@hdp4 ~]# consul agent -ui -data-dir /tmp/consul -bind 10.0.( 


你 可 以 查看 线 上 Demo. 
线 上 Demo 可 以 访问 所 有 的 数据 中 心 .我 们 也 设置 了 Demo 的 端点 : AMS2 ( 阿 姆 斯 特 
F) , SF01( 晶 金山 ) 和 NY3( 纽 约 ). 


下 一 步 


我 们 的 入 门 指南 完成 了 .查看 下 一 页 来 了 解 如 何 继续 你 与 Consul 的 旅程 ! 
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接 下 来 的 

入 门 指南 告 束 了 , 布 望 你 能 看 到 Consul 是 简单 多 用 的 .他 拥有 一 些 强 大 的 功能 .我 们 在 
这 个 指南 里 覆盖 了 些 功能 的 基础 . 

Consul 采 用 对 运 维和 开发 者 友好 的 方式 进行 设计 ,让 它 完 美的 适用 于 现代 的 弹性 基础 


设施 . 
接 下 来 可 以 使 用 这 些 资源 做 更 深入 的 了 解 . 


e 文档 -文档 是 更 深入 的 Consul 功 能 参考 .包括 Consul 内 部 操作 的 技术 细节 

e 指南 - 这 部 分 提供 很 多 Consul 的 入 门 指南 ,包括 如 何 启 动 一 个 数据 中 心 . 

e 示例 - 这 个 Consul 的 Github 库 中 还 在 进行 中 的 示例 目录 包含 很 多 使 用 示例 ,帮助 
你 更 好 的 根据 你 的 需要 使 用 Consul 的 功能 


Consul Template 简介 


Consul Template 提供 一 个 方便 的 方式 从 Consul 获 取 数 据 通过 consul-template 的 后 
台 程 序 保 存 到 文件 系统 


这 个 后 人 台 进 程 监控 Consul 示 例 的 变化 并 更 新 任意 数量 的 模板 到 文件 系统 .作为 一 个 附 
件 功能 ed uper template 可 以 运行 任何 命令 .可 以 查看 示例 部 分 看 这 
个 功能 将 会 对 哪些 应 用 场景 产生 帮助 . 


安装 


你 可 以 在 发 布 页 下 载 发 布 包 . 如 果 你 希望 自己 编译 请 查看 说 明文 档 . 


查看 全 部 选项 ,使 用 以 下 命令 


consul-template -h 


444 
查询 ^"'demo.consul.io ^^ 3^ ^^'Consul' 实例 (agent ) . 泻 染 模板 文件 
``/tmp/template.ctmpl1``` RAZ] ^^^ /tmp/result^ ^'^, %47```Consul 


-template "^ 服务 直到 直到 手动 结束 : 


consul-template \ -consul demo.consul.io \ -template 
"Itmp/template.ctmpl:/tmp/result" 


查询 本 地 的 `、`Consul `` zA (agent), -ERRA E E AUS RRMH * ^^^ Ngin 
Uo de^ Consul ` 不 可 用 30 秒 重 试 一 次 : 


consul-template \ -consul 127.0.0.1:8500 \ -template 
"/tmp/template.ctmpl:/var/www/nginx.conf:service nginx restart" \ -retry 30s \ -once 


&ig—4-^^^ Consul 实例 , 泻 涩 多 个 模板 并 作为 服务 直到 停止 : 


consul-template Y -consul my.consul.internal:6124 X -template 
"Itmp/nginx.ctmpl:/var/nginx/nginx.conf:service nginx restart" \ -template 
"/tmp/redis.ctmpl:/var/redis/redis.conf:service redis restart" \ -template 
"Itmp/haproxy.ctmpl:/var/haproxy/haproxy.conf" 


查询 一 个 需要 权限 验证 的 ` ^ n Consul ` 人 实例 ,将 泻 染 后 的 模板 输出 到 控制 台 而 不 写 入 
磁盘 ,在 这 个 例子 中 ` - template’ 的 第 二 个 和 第 三 个 参数 是 必须 的 但 是 被 忽略 了 ， 
这 个 文件 将 不 会 被 写 入 磁盘 ,命令 也 不 会 被 执行 ， 


$ consul-template | -consul my.consul.internal:6124 Y -template 
"/tmp/template.ctmpl:/tmp/result:service nginx restart" -dry 


f$ ASSL 3t fT^ ^^ Consul ^ #74: 


$ consul-template X -consul 127.0.0.1:8543 V -ssl V -ssl-cert /path/to/client/cert.pem 
V -ssl-ca-cert /path/to/ca/cert.pem Y -template "/tmp/template.ctmpl:/tmp/result" V - 
dry \ -once 


#79 `` consul` 并 尼 动 一 个 子 进 程 .模板 的 变化 会 发 送 指令 给 予 进 程 , 详 细 的 说 明 请 
查看 [这 里 ] (https://github.com/hashicorp/consul-template#exec-mode 
Ne 


$ consul-template \ -template "/tmp/in.ctmpl:/tmp/result" \ -exec "/sbin/my-server 


HHHH 配置 文件 
```Consul-Template``` 配置 文 件 是 使 用 [HashiCorp Configuration Langua 
ge (HCL)](https://github.com/hashicorp/hcil) 编 写 的 .这 意味 着 ```Consu 


1 Template``` 是 和 JSON 兼 容 的 ,查看 更 多 信息 请 查看 [HCL 规范 ] (https://git 
hub.com/hashicorp/hcl) 


配置 文件 语法 支持 上 面 的 所 有 的 选项 ,除非 在 表格 中 进行 标明 , 
~*json 


// 这 是 要 连接 的 Consul Agent 的 地 址 ,默认 为 127.0.0.1:8500. 这 是 Consul 的 默 
认 绑 定 地 址 和 端口 ， 


// 不 建议 你 直接 与 Consul% Server 直 接 进行 交互 ,请 与 本 地 的 Consul Agent 进 
FRE ,这样 做 是 有 一 些 原 因 

// 最 重要 的 是 本 地 agent 可 以 复 用 与 Server 的 连接 ,减少 HTTP 的 连接 数 , 另 外 这 个 地 
址 更 好 记 ， 

consul = "127.0.0.1:8500" 


这 是 用 于 连接 Consul 的 ACL token， 如 果 你 的 集群 未 启用 就 不 需要 设置 ， 
// 这 个 选项 也 可 以 通过 环境 变量 CONSUL TOKEN 来 进行 设置 
token = "abcd1234" 


// 这 是 监听 出 发 reload 事 件 的 信号 , 默认 值 如 下 所 示 , 将 这 个 值 设置 为 空 将 引起 CT, 
从 而 不 监听 reload 事 件 
reload signal = "SIGHUP" 


// 这 是 监听 出 发 core dump 事 件 的 信号 ,默认 值 如 下 所 示 , 将 这 个 值 设 置 为 空 将 引起 C 
T ,从 而 不 监听 core dump 信 号 
dump signal = "SIGQUIT" 


// 这 是 监听 出 发 graceful stop 事 件 的 信号 ,默认 值 如 下 所 示 , 将 这 个 值 设 置 为 空 将 
引起 CT ， 从 而 不 监听 graceful stop 信 号 
kill signal = "SIGINT" 


// 这 是 连接 Consul 的 重 试 时 间 .Consul Template 是 高 容错 的 设计 ,这 意味 着 ,出 现 
失败 他 不 会 退出 ,而 按照 

// 分 布 式 系 统 的 惯例 进行 指数 补偿 和 重 试 来 等 待 集群 恢复 ， 

retry = "10s" 


// This is the maximum interval to allow "stale" data. By defaul 
t, only the 

// Consul leader will respond to queries; any requests to a foll 
ower will 

// forward to the leader. In large clusters with many requests, 
this is not as 

// scalable, so this option allows any follower to respond to a 
query, so long 

// as the last-replicated data is within these bounds. Higher va 
lues result in 

// less cluster load, but are more likely to have outdated data. 
// 这 是 允许 陈旧 数 据 的 最 大 时 间 .Consul 默 认 只 有 领袖 对 请 求 进 行 相应 .所 有 对 追随 者 
的 请 求 将 被 转发 给 领袖 ， 

a 
应 查询 ,只 要 最 后 复制 的 数据 

^ 在 这 个 范围 内 ,数值 越 高 ， 越 减少 集群 负载 ,但 是 更 容 多 接受 到 过 期 数据 ， 

max stale = "10m" 


// 这 是 10g 的 等 级 ， he ag 青 打开 debug AS, 这 样 我 们 可 以 更 好 的 定位 
问题 ,这 个 选项 也 可 用 在 命令 
log level = "warn" 


// 这 是 存放 Consul Template 进程 的 PID 文 件 的 路 径 , 如 果 你 计划 发 送 定 制 的 信号 
到 这 个 进程 这 会 比较 有 用 ， 
pid file = "/path/to/pid" 


// 这 是 一 个 静止 定时 器 ,他 定义 了 在 模板 泻 染 之 前 等 待 集群 达到 一 致 状态 的 最 小 和 最 大 
时 间 . 

// 这 对 于 一 些 变化 较 大 的 系统 中 比较 有 用 ， 可 以 减少 模板 泻 梁 的 次 数 

wait = "5s:10s" 


// 这 是 Vault 配 置 的 开始 
// Vault 是 HashiCorp 的 另外 一 个 产品 
vault { 
// This is the address of the Vault leader. The protocol (http 
(s)) portion 
// of the address is required. 
address = "https://vault.service.consul:8200" 


// This is the token to use when communicating with the Vault 
server. 

// Like other tools that integrate with Vault, Consul Template 
makes the 

// assumption that you provide it with a Vault token; it does 
not have the 

// incorporated logic to generate tokens via Vault's auth meth 
ods. 

// 

// This value can also be specified via the environment variab 
le VAULT TOKEN. 

token = "abcd1234" 


// This option tells Consul Template to automatically renew th 
e Vault token 

// given. If you are unfamiliar with Vault's architecture, Vau 
lt requires 

// tokens be renewed at some regular interval or they will be 
revoked. Consul 

// Template will automatically renew the token at half the lea 
se duration of 

// the token. The default value is true, but this option can b 
e disabled if 

// you want to renew the Vault token using an out-of-band proc 
ess. 

// 

// Note that secrets specified in a template (using {{secret}} 
for example) 

// are always renewed, even if this option is set to false. Th 
is option only 

// applies to the top-level Vault token itself. 

renew - true 


// This section details the SSL options for connecting to the 
Vault server. 

// Please see the SSL options below for more information (they 

are the same). 

ssl ( 


OA 


} 
} 
// 这 部 分 配置 请 求 的 基本 的 权限 验证 信息 
auth { 

enabled = true 

username - "test" 

password - "test" 
// 这 部 分 配置 连接 到 Consul 服 务 器 的 SSL 信 息 ， 
ssl { 


// 使 用 SSL 需 要 先 打 开 这 个 开关 
enabled = true 


// This enables SSL peer verification. The default value is "t 
rue", which 

// will check the global CA chain to make sure the given certi 
ficates are 

// valid. If you are using a self-signed certificate that you 
have not added 

// to the CA chain, you may want to disable SSL verification. 
However, please 

// understand this is a potential security vulnerability. 

verify - false 


// This is the path to the certificate to use to authenticate. 

If just a 

// certificate is provided, it is assumed to contain both the 
certificate and 

// the key to convert to an X509 certificate. If both the cert 
ificate and 

// key are specified, Consul Template will automatically combi 
ne them into an 

// X509 certificate for you. 

cert = "/path/to/client/cert" 

key = "/path/to/client/key" 


// This is the path to the certificate authority to use as a C 
A. This is 

// useful for self-signed certificates or for organizations us 
ing their own 

// internal certificate authority. 

ca_cert = "/path/to/ca" 


} 


// 设置 连接 到 Sys10g 服 务 器 的 配置 
// 用 于 进行 日 志 记 录 Sys1log { 
// 打开 开关 
enabled = true 


// 设备 名 称 


facility = "LOCAL5" 
} 


// This block defines the configuration for de-duplication mode. 
Please see the 
// de-duplication mode documentation later in the README for mor 
e information 
// on how de-duplication mode operates. 
deduplicate { 
// This enables de-duplication mode. Specifying any other opti 
ons also enables 
// de-duplication mode. 
enabled = true 


// This is the prefix to the path in Consul's KV store where d 
e-duplication 

// templates will be pre-rendered and stored. 

prefix = "consul-template/dedup/" 


} 


// This block defines the configuration for exec mode. Please se 
e the exec mode 
// documentation at the bottom of this README for more informati 
on on how exec 
// mode operates and the caveats of this mode. 
exec { 

// This is the command to exec as a child process. There can b 
e only one 

// command per Consul Template process. 

command = "/usr/bin/app" 


// This is a random splay to wait before killing the command. 
The default 

// value is © (no wait), but large clusters should consider se 
tting a splay 

// value to prevent all child processes from reloading at the 
same time when 

// data changes occur. when this value is set to non-zero, Con 
sul Template 

// will wait a random period of time up to the splay value bef 
ore reloading 

// or killing the child process. This can be used to prevent t 
he thundering 

// herd problem on applications that do not gracefully reload. 

splay - "5s" 


// This defines the signal that will be sent to the child proc 
ess when a 

// change occurs in a watched template. The signal will only b 
e sent after 

// the process is started, and the process will only be starte 
d after all 

// dependent templates have been rendered at least once. The d 


efault value 

// is "" (empty or nil), which tells Consul Template to restar 
t the child 

// process instead of sending it a signal. This is useful for 
legacy 

// applications or applications that cannot properly reload th 
eir 

// configuration without a full reload. 

reload signal - "SIGUSR1" 


// This defines the signal sent to the child process when Cons 
ul Template is 

// gracefully shutting down. The application should begin a gr 
aceful cleanup. 

// If the application does not terminate before the ^"kill time 
out it will 

// be terminated (effectively "kill -9"). The default value is 

"SIGTERM". 

kill signal = "SIGINT" 


// This defines the amount of time to wait for the child proce 
ss to gracefully 

// terminate when Consul Template exits. After this specified 
time, the child 

// process will be force-killed (effectively "kill -9"). The d 
efault value is 

VUE SD ese 

kill timeout - "2s" 


j 


/ 这 部 分 定义 了 对 模板 的 配置 , 和 其 他 配置 块 不 同 .这 部 分 可 以 针对 不 同 模板 配置 多 次 ， 
也 可 以 在 CLI 命 令 
// 直接 进行 配置 
template { 
// 这 是 输入 模板 的 配置 文件 路 径 ， 必 选项 
source = "/path/on/disk/to/template.ctmpl" 


// 这 是 源 模 板 泻 染 之 后 存放 的 路 径 ， 如果 父 目录 不 存在 Consu1 Template 会 党 试 进 
行 创建 
destination = "/path/on/disk/where/template/will/render.txt" 


// This is the optional command to run when the template is re 
ndered. The 

// command will only run if the resulting template changes. Th 
e command must 

// return within 30s (configurable), and it must have a succes 
sful exit code. 

// Consul Template is not a replacement for a process monitor 
or init system. 

// 这 是 当 模 板 泻 染 完 成 后 可 选 的 要 执行 的 命令 ,这 个 命令 只 会 在 模板 发 生 改 变 后 才 会 
运行 nuc Garr 

// 内 进行 返回 (可 配置 ), 必须 返回 一 个 成 功 的 退出 码 .Consu1 Template z KERA 

进程 监视 或 者 init 系统 


// 的 功能 
command = "restart service foo" 


// 这 是 最 大 的 等 待命 令 返 回 的 时 间 , 默认 是 30 秒 
command timeout = "60s" 


// 这 是 泻 染 后 的 文件 的 权限 ,如 果 不 设置 , Consul Template 将 去 匹配 之 前 已 经 存 


在 的 文件 的 权限 ， 


// 如 果 文 件 不 存在 ,权限 会 被 设置 为 0644 
perms = 0600 


// 这 个 选项 对 泻 梁 之 前 的 文件 进行 备份 ,他 保持 一 个 备份 ， 
// 这 个 选项 在 发 生意 外 更 高 时 ,有 一 个 回 滚 策略 ， 
backup = true 


// 模板 的 分 隔 符 ,默认 是 "{{" 和 "}}" .但 是 对 于 一 些 模板 用 其 他 的 分 隔 符 可 能 更 好 
// 可 以 避免 与 本 身 的 冲突 

left delimiter = "{{" 

right delimiter = "jj" 


// 这 是 最 小 和 最 大 等 待 泻 染 一 个 新 模板 和 执行 命令 的 时 间 .使 用 分 号 个 号 ,如 果 忽 


略 最 大 值 , 最 大 

// 人 和 值 会 被 设置 为 最 小 值 的 4 倍 ,这 个 选项 没有 默认 值 .这 个 值 相 对 全 局 所 以 的 等 待 时 
间 有 最 高 优先 级 

wait = "2s:6s" 
} 


注意 : 不 是 所 有 的 选项 都 是 必 选 的 .例如 : 如 果 你 没有 使 用 Vault 你 不 用 设置 这 一 
块 . 类 似 的 你 没有 使 用 syslog 系 统 你 也 不 需要 指定 syslog 配 置 


为 了 更 加 安全 ，token 也 可 以 从 环境 变量 里 读 取 ,使 用 CONSUL TOKEN 和 
VAULT TOKEN .强烈 建议 你 不 要 把 token 放 到 未 加 密 的 文本 配置 文件 中 . 


查询 nyc3 demo 的 Consul 示 例 , 演 染 模板 /tmp/template.ctmpl 
到 /tmp/result .运行 Consul Template 直 到 服务 停止 


consul = "nyc3.demo.consul.io" 
template { 
source "/tmp/template.ctmpl" 


j 


destination "/tmp/result" 


如 果 一 个 用 一 个 目录 替换 文件 ,所 以 这 个 目录 中 的 文件 会 递归 的 安装 Go walk BA 4 
顺序 进行 合 并 .所 以 如 果 多 个 文件 定义 了 consul key 则 最 后 一 个 将 会 被 使 用 ,注意 ， 
符号 链接 不 会 被 加 入 . 


在 命 


令 行 指定 的 选项 ,优先 于 配置 文件 


模板 语法 


Consul Template 使 用 了 Go 的 模板 语法 .如 果 你 对 他 的 语法 不 熟悉 建议 你 读 下 文档 . 
他 的 语法 看 起 来 与 Mustache, Handlebars, 或 者 Liquid 类 似 . 


在 Go 提供 的 模板 函数 之 外 ,Consul Template 暴 露 了 以 下 的 函数 : 
API 有 函数 


datacenters 
查询 目录 中 的 所 有 数据 中 心 .使 用 以 下 语法 : 


{{datacenters}} 
file 
读 取 并 输出 磁盘 上 的 本 地 文件 ,如 果 无 法 读 取 产 生 一 个 错误 .使 用 如 下 语法 


{{file "/path/to/local/file"}} 


这 个 例子 将 输出 /path/to/local/file 文件 内 容 到 模板 . ZRRFSEREE 
板 中 被 处 理 


key 
查询 Consul 指 定 key 的 值 ,如 果 key 的 值 不 能 转换 为 字符 串 , 将 产生 错误 .使 用 如 下 语法 : 


{{key "service/redis/maxconns@east-aws"}} 


上 面 的 例子 查询 了 在 east-aws 数据 中 心 的 service/redis/maxconns 的 值 .如 
果 和 忽略 数据 中 心 参数 ,将 会 查询 本 地 数据 中 心 的 值 : 


{{key "service/redis/maxconns"}} 


Consul 键 值 结 构 的 美妙 在 于 ,这 完全 取决 于 你 | 


key_or_default 
查询 Consul 中 指定 的 key 的 值 ,如 果 key 不 存在 , 则 返回 默认 值 .使 用 方式 如 下 


{{key_or_default "service/redis/maxconnsQeast-aws" "5"}} 


注意 Consul Template 使 用 了 多 个 阶段 的 运算 .在 第 一 阶段 的 运算 如 果 Consul 没 有 返 
回 值 , 则 会 一 直 使 用 默认 值 .后 续 模 板 解析 中 如 果 值 存在 了 则 会 读 取 引 实 的 值 . 这 很 重 
要 , 运 维 Consul Templae 不 会 因为 key or default 没 找到 key 而 阻塞 模板 的 的 浑 
染 .即使 key 存 在 如 果 Consul 没 有 按时 返回 这 个 数据 ,也 会 使 用 默认 值 来 进行 替代 


Is 


查看 Consul 的 所 有 以 指定 前 缓 开头 的 key-value 对 .如 果 有 值 无 法 转换 成 字符 串 则 会 
产生 一 个 错误 : 


{{range ls "service/redis@east-aws"}} 


{{.Key}} {{.Value}}{{end}} 


如 果 Consul 实 例 在 east-aws 数据 中 心 存在 这 个 结构 service/redis , 泻 染 后 的 
模板 应 该 类 似 这 样 : 


minconns 2 
maxconns 12 


如 果 你 忽略 数据 中 心 属性 , 则 会 返回 本 地 数据 中 心 的 查询 结果 . 


node 


查询 目录 中 的 一 个 节点 信息 


{{node "node1"}} 

如 果 未 指定 任何 参数 , 则 当前 agent 所 在 节点 将 会 被 返回 : 
{{node}} 

你 可 以 指定 一 个 可 选 的 参数 来 指定 数据 中 心 : 


{{node "nodei" "@east-aws"}} 


如 果 指 定 的 节点 没有 找到 则 会 返回 nil .如 果 节 点 存在 就 会 列 出 节点 的 信息 和 节点 
提供 的 服务 . 


{{with node}}{{.Node.Node}} ({{.Node.Address}}){{range .Services 
}} 

{{.Service}} {{.Port}} ({{.Tags | join ","}}){{end}} 
{{end}} 


nodes 


查询 目录 中 的 全 部 节点 ,使 用 如 下 语法 
{{nodes}} 


这 个 例子 会 查询 Consul 的 默认 数据 中 心 .你 可 以 使 用 可 选 参 数 指 定 一 个 可 选 参 数 来 指 
定数 据 中 心 ; 


{{nodes "@east-aws"}} 


这 个 例子 会 查询 east-aws 数据 中 心 的 所 有 几 点 . 
Secret 


查询 Vault 中 指定 路 径 的 密 恶 .如 果 指 定 的 路 径 不 存在 或 者 vault 的 Token 没 有 
足够 权限 去 读 取 指 定 的 路 径 ,将 会 产生 一 个 错误 .如 果 路 径 存 在 但 是 key 不 存在 则 返 
回 «no value». 


{{with secret "secret/passwords"}}{{.Data.password}}{{end}} 


可 以 使 用 如 下 字段 : 


LeaseID - the unique lease identifier 

LeaseDuration - the number of seconds the lease is valid 
Renewable - if the secret is renewable 

Data - the raw data - this is a map[string]interface{}, so it ca 
n be queried using Go's templating "dot notation" 

If the map key has dots "." in it, you need to access the value 
using the index function: 


{{index ,Data "my.key.with.dots"}} 

If additional arguments are passed to the function, then the ope 
ration is assumed to be a write operation instead of a read oper 
ation. The write operation must return data in order to be valid 
. This is especially useful for the PKI secret backend, for exam 
ple. 


{{ with secret "pki/issue/my-domain-dot-com" "common_name=foo.ex 
ample.com" }} 
{{ .Data.certificate }} 


{{ end }} 


The parameters must be key=value pairs, and each pair must be it 
s own argument to the function: 


{{ secret "path/" "a=b" "c=d" "e=f" }} 

Please always consider the security implications of having the c 

ontents of a secret in plain-text on disk. If an attacker is abl 

e to get access to the file, they will have access to plain-text 
secrets. 


Please note that Vault does not support blocking queries. As a result, Consul 
Template will not immediately reload in the event a secret is changed as it does 
with Consul's key-value store. Consul Template will fetch a new secret at half the 
lease duration of the original secret. For example, most items in Vault's generic 
secret backend have a default 30 day lease. This means Consul Template will 
renew the secret every 15 days. As such, it is recommended that a smaller lease 
duration be used when generating the initial secret to force Consul Template to 
renew more often. 


secrets 


Query Vault to list the secrets at the given path. Please note this requires Vault 
0.5+ and the endpoint you want to list secrets must support listing. Not all 
endpoints support listing. The result is the list of secret names as strings. 


{{range secrets "secret/"}}{{.}}{{end}} 


The trailing slash is optional in the template, but the generated secret dependency 
will always have a trailing slash in log output. 


To iterate and list over every secret in the generic secret backend in Vault, for 
example, you would need to do something like this: 


{{range secrets "secret/"}} 

{{with secret (printf "secret/%s" .)}} 
{{range $k, $v := .Data}} 

(Sk): {{$v}} 

{{end}} 

{{end}} 

{{end}} 


You should probably never do this. Please also note that Vault does not support 
blocking queries. To understand the implications, please read the note at the end 
of the secret function. 


service 


查询 Consu| 中 匹配 表达 式 的 服务 .语法 如 下 : 


{{service "release.web@east-aws"}} 


上 面 的 例子 查询 Consul 中 ,在 east-aws 数据 中 心 存在 的 健康 的 web 服务 .tag 和 数 
据 中 心 参数 是 可 选 的 .从 当前 数据 中 心 查询 所 有 节点 的 web 服务 而 不 管 tag, 查 询 语 
法 如 下 : 


{{service "web"}} 


这 个 函数 返回 []*HealthService 结构 .可 按照 如 下 方式 应 用 到 模板 : 


{{range service "web@data center"}} 
server {{.Name}} {{.Address}}:{{.Port}}{{end}} 


产生 如 下 输出 : 


server nyc web 01 123.456.789.10:8080 
server nyc web 02 456.789.101.213:8080 


默认 值 会 返回 健康 的 服务 ,如 果 你 想 获取 所 有 服务 ,可 以 增加 any 选项 ,如 下 


{{service "web" "any"}} 


这 样 就 会 返回 注册 过 的 所 有 服务 ,而 不 论 他 的 状态 如 何 . 


如 果 你 想 过 滤 指 定 的 一 个 或 者 多 个 健康 状态 ,你 可 以 通过 过 号 隔 开 多 个 健康 状态 : 


{{service "web" "passing, warning") 


这 样 将 会 返回 被 他 们 的 节点 和 服务 级 别 的 检查 定义 标记 为 "passing" 或 者 
"Warning" 的 服务 . 请 注意 过 号 是 OR 而 不 是 AND VAR. 


指定 了 超过 一 个 状态 过 滤 , 并 包含 any 将 会 返回 一 个 错误 .因为 any 是 比 所 有 状态 
更 高 级 的 过 滤 . 


后 面 这 2 种 方式 有 些 架 构 上 的 不 同 : 


{{service "web"}} 
{{service "web" "passing"}} 


前 者 会 返回 Consul 认 为 healthy 和 passing 的 所 有 服务 .后 者 将 返回 所 有 已 经 在 

Consul 注 册 的 服务 .然后 会 执行 一 个 客户 端的 过 滤 . 通 常 如 果 你 想 获取 健康 的 服务 ,你 

应 该 不 要 使 用 passing 参数 ,直接 忽略 第 三 个 参数 即 可 .然而 第 三 个 参数 在 你 想 查询 
passing 或 者 warning 的 服务 会 比较 有 用 ,如 下 : 


{{service "web" "passing, warning") 


服务 的 状态 也 是 可 见 的 ,如 果 你 想 自己 做 一 些 额 外 的 过 滤 , 语 法 如 下 : 


{{range service "web" "any"}} 
{{if eq .Status "critical")) 
// Critical state! {{end}} 
{{if eq .Status "passing"}} 
// Ok{{end}} 


执行 命令 时 ,在 Consul 将 服务 设置 为 维护 模式 ,只 需要 在 你 的 命令 上 包 上 Consul 的 
maint 调用 : 


#!/bin/sh 

set -e 

consul maint -enable -service web -reason "Consul Template updat 
eq" 

service nginx reload 

consul maint -disable -service web 


另外 如 果 你 没有 安装 Consul agent, 你 可 以 直接 调用 API 请 求 : 


#!/bin/sh 

set -e 

curl -X PUT "http://$CONSUL_HTTP_ADDR/v1/agent/service/maintenan 
ce/web?enable=true&reason=Consul+Template+Updated" 

service nginx reload 

curl -X PUT "http://$CONSUL_HTTP_ADDR/v1/agent/service/maintenan 
ce/web?enable=false" 


services 


查询 Consu| 目 录 中 的 所 有 服务 ,使 用 如 下 语法 : 


{{services}} 


这 个 例子 将 查询 Consul 的 默认 数据 中 心 ,你 可 以 指定 一 个 可 选 参数 来 指定 数据 中 心 ; 


{{services "@east-aws"}} 


请 注意 : services BRA service KH, service 接受 更 多 参数 并 且 查 询 
监控 的 服务 列表 .这 个 查询 Consul 目 录 并 返回 一 个 服务 的 tag 的 Map, 如 下 : 


{{range services)? 


{{.Name }} 
{{range .Tags}} 
{{.}}{{end}} 

{{end}} 


tree 


查询 所 有 指定 前 组 的 key-value 值 对 ,如 果 其 中 的 值 有 无 法 转换 为 字符 串 的 则 引发 错 


a 
TR! 


{{range tree "service/redis@east-aws"}} 


{{.Key}} {{.Value}}{{end}} 


t Consul BI 7E east-aws 数据 中 心 有 一 个 service/redis 结构 ,模板 的 泻 染 
结果 类 似 下 面 : 


minconns 2 
maxconns 12 
nested/config/value "value" 


和 ls ^H, tree 返回 前 组 下 的 所 有 key 和 Unix 的 tree 命 令 比较 像 .如 果 忽 略 数据 中 
心 参数 , 则 会 使 用 本 地 数据 中 心 


帮助 函数 


byKey 


将 tree 返回 的 key-value 值 对 结果 创建 一 个 map, 这 个 map 根 据 他 们 的 顶级 目录 进 
行 组 合 .例如 如 果 Consul 的 kv 存储 如 下 结构 : 


groups/elasticsearch/esi 
groups/elasticsearch/es2 
groups/elasticsearch/es3 
services/elasticsearch/check elasticsearch 
services/elasticsearch/check indexes 


使 用 下 面 的 模板 : 


{{range $key, $pairs := tree "groups" | byKey}}{{$key}}: 
(frange $pair := $pairs}} {{.Key}}={{.Value}} 
{{end}}{{end}} 


结果 如 下 : 


elasticsearch: 
esi=1 
es2=1 
es3=1 


注意 顶部 的 key 会 被 从 key 的 值 中 剥离 出 来 .如 果 在 剥离 前 组 后 没有 前 缓 , 值 会 被 从 列 
表 移 除 . 
结果 的 对 会 被 映射 为 map, 使 用 可 以 使 用 key 来 访问 一 个 单独 的 值 : 
{{$weights := tree "weights"}} 
{{range service "release.web"}} 
{{$weight := or (index $weights .Node) 100}} 


server {{.Node}} {{.Address}}:{{.Port}} weight {{$weight}}{{en 
d}} 


byTag 
将 被 service 或 者 services WHARF RK, tz tag xz MR F 6| Map. 


(frange $tag, $services := service "web" | byTag}}{{$tag}} 
{{range $services}} server {{.Name}} {{.Address}}:{{.Port}} 
{{end}}{{end}} 


contains 


检查 目标 是 否 包含 在 枚 举 的 元 素 中 


{{ if .Tags | contains "production" }} 
# 


{{ end }} 


env 

读 取 当前 进程 可 以 访问 的 环境 变量 ， 
{{env "CLUSTER ID") 

3 Ae f CST VA hor ia: 
{{env "CLUSTER ID" | toLower}} 

explode 

将 tree 或 者 ls 8 ACR ERU RR dE E map, M KT AE Fe 3f ya, 
{{ tree "config" | explode 1) 

注意 ; 解 开 后 ,你 将 丢失 所 有 的 关于 键 值 对 的 元 数据 . 

ART Vig eR ER BDA: 


{{ with tree "config" | explode }} 

{{.a.b.c}}{{ end }} 
注意 ; 你 需要 在 Consul 中 保存 有 一 个 合理 的 格式 的 数据 .可 以 查看 Go 的 text/template 
包 获 取 更 多 信息 . 
in 


检查 目标 十 分 在 一 个 可 枚 举 的 元 素 中 . 


{ if in .Tags "production" }} 
Tan 
(( end 33 

loop 

接受 多 个 参数 ,行为 受 这 些 参 数 的 影响 ， 

如 果 给 1oop 一 个 数字 ,他 讲 返回 一 个 goroutine ,开始 于 0 循环 直到 等 于 参数 的 
值 : 


{{range loop 5}} 
# Comment{{end}} 


如 果 给 2 个 数字 , 则 这 个 函数 返回 一 个 goroutine 从 第 一 个 数字 开始 循环 直到 等 于 
第 二 个 参数 的 值 . 


(frange $i := loop 5 8}} 
stanza-{{$i}}{{end}} 


Note: It is not possible to get the index and the element since the function returns 
a goroutine, not a slice. In other words, the following is not valid: 


# Will NOT work! 
{{range $i, $e := loop 5 8}} 
# ...{{end}} 


join 
将 提供 的 列表 作为 管道 与 提供 的 字符 串 连 接 : 
{{$items | join ","}} 


trimSpace 


对 输入 的 内 容 移 除 掉 空 白 ,tab 和 换行 符 


{ file "/etc/ec2 version"| trimSpace }} 


parseBool 


将 给 定 的 字符 串 解 析 为 布尔 4 


{{"true" | parseBool}} 


这 个 可 以 与 一 个 key 检 查 和 条 件 检查 相 结合 .如 下 : 


{{if key "feature/enabled" | parseBool}}{{end}} 


parseFloat 


将 给 定 的 字符 串 解析 为 10 进 制 float64 类 型 数字 : 


{{"1.2" | parseFloat}} 


parselnt 


将 给 定 字符 串 解 析 为 10 禁 止 int64 类 型 数字 : 


{{"i" | parseInt 


这 个 可 以 与 其 他 的 帮助 函数 结合 使 用 ,例如 


{{range $i := loop key "config/pool size" | parseInt}} 
.. {{end}} 
parseJSON 
将 输入 ,通常 是 通过 key 获 取 的 值 ,解析 成 JSON 


Takes the given input (usually the value from a key) and parses the result as 
JSON: 


{{with $d := key "user/info" | parseJSON}}{{$d.name}}{{end}} 


注意 : Consul Template 计 算 模 板 很 多 次 .第 一 次 计算 时 会 是 空 ,因为 数据 还 未 载 入 ,这 
意味 着 我 们 需要 检查 空 的 响应 .例如 : 


{{with $d := key "user/info" | parseJSON}} 
{{if $d}} 


{{end}} 
{fend}} 


它 只 适用 简单 的 key, 但 是 如 果 你 想 遍 历 key 或 者 使 用 index 函 数 会 失败 .将 要 访问 的 代 
码 包含 在 {{ if $d }}...{f{end}} 之 中 就 够 了 . 


Alternatively you can read data from a local JSON file: 


{{with $d := file "/path/to/local/data.json" | parseJSON}}{{$d.s 
ome_key}}{{end}} 


parseUint 


Takes the given string and parses it as a base-10 int64: 


(("1" | parseUint}} 


See parselnt for examples. 


THHHE plugin 


Takes the name of a plugin and optional payload and executes a Consul Template 
plugin. 


{{plugin "my-plugin"}} 


This is most commonly combined with a JSON filter for customization: 


{{tree "foo" | explode | toJSON | plugin "my-plugin"}} 


Please see the plugins section for more information about plugins. 


regexMatch 


Takes the argument as a regular expression and will return true if it matches on 
the given string, or false otherwise. 


{{"foo.bar" | regexMatch "foo([.a-z]+)"}} 


regexReplaceAll 


Takes the argument as a regular expression and replaces all occurrences of the 
regex with the given string. As in go, you can use variables like $1 to refer to 
subexpressions in the replacement string. 


{{"foo.bar" | regexReplaceAll "foo([.a-z]+)" "$1"}} 


replaceAll 


Takes the argument as a string and replaces all occurrences of the given string 
with the given string. 


{{"foo.bar" | replaceAll "." "_"}} 


This function can be chained with other functions as well: 
{{service "web"}}{{.Name | replaceAll ":" "_"}}{{end}} 

split 

Splits the given string on the provided separator: 


{{"foo\nbar\n" | split "\n"}} 


This can be combined with chained and piped with other functions: 


{{key "foo" | toUpper | split "^n" | join ","}} 


timestamp 


Returns the current timestamp as a string (UTC). If no arguments are given, the 
result is the current RFC3339 timestamp: 


{{timestamp}} // e.g. 1970-01-01T00:00:00Z 


If the optional parameter is given, it is used to format the timestamp. The magic 
reference date Mon Jan 2 15:04:05 -0700 MST 2006 can be used to format the 
date as required: 


{{timestamp "2006-01-02"}} // e.g. 1970-01-01 


See Go's time.Format() for more information. 


As a special case, if the optional parameter is "unix", the unix timestamp in 
seconds is returned as a string. 


{{timestamp "unix"}} // e.g. 0 


toJSON 


Takes the result from a tree or Is call and converts it into a JSON object. 


{{ tree "config" | explode | toJSON 3) // e.g. {"admin":{"port": 
1234}, "maxconns":5, minconns":2) 


Note: This functionality should be considered final. If you need to manipulate keys, 
combine values, or perform mutations, that should be done outside of Consul. In 
order to keep the API scope limited, we likely will not accept Pull Requests that 
focus on customizing the toJSON functionality. 


toJSONPretty 


Takes the result from a tree or Is call and converts it into a pretty-printed JSON 
object, indented by two spaces. 


{{ tree "config" | explode | toJSONPretty }} 


"admin": ( 
"port": 1234 
ty 


"maxconns": 5, 
"minconns": 2, 


j 
DA 


Note: This functionality should be considered final. If you need to manipulate keys, 
combine values, or perform mutations, that should be done outside of Consul. In 
order to keep the API scope limited, we likely will not accept Pull Requests that 
focus on customizing the toJSONPretty functionality. 


toLower 


Takes the argument as a string and converts it to lowercase. 


{{key "user/name" | toLower}} 


See Go's strings. ToLower() for more information. 
toTitle 


Takes the argument as a string and converts it to titlecase. 


{{key "user/name" | toTitle}} 


See Go's strings.Title() for more information. 
toUpper 


Takes the argument as a string and converts it to uppercase. 


{{key "user/name" | toUpper}} 


See Go's strings.ToUpper() for more information. 

toYAML 

Takes the result from a tree or Is call and converts it into a pretty-printed YAML 
object, indented by two spaces. 


{{ tree "config" | explode | toYAML }} 
Vas 
admin: 
port: 1234 
maxconns: 5 
minconns: 2 
2a 


Note: This functionality should be considered final. If you need to manipulate keys, 
combine values, or perform mutations, that should be done outside of Consul. In 
order to keep the API scope limited, we likely will not accept Pull Requests that 
focus on customizing the toYAML functionality. 


Math Functions 
The following functions are available on floats and integer values. 
add 


Returns the sum of the two values. 


fi added oe hye 


This can also be used with a pipe function. 


{{ 1 | add 2 } ⁄/3 
subtract 
Returns the difference of the second value from the first. 


{{ subtract 2 5 }} // 3 


This can also be used with a pipe function. 
{{ 5 | subtract 2 }} 
Please take careful note of the order of arguments. 


multiply 


Returns the product of the two values. 


{{ multiply 2 2 }} // 4 


This can also be used with a pipe function. 
{{ 2 | multiply 2 }} // 4 
divide 
Returns the division of the second value from the first. 


{{ divide 2 10 }} // 5 


This can also be used with a pipe function. 


{{ 10 | divide 2 }} // 5 


Please take careful note of the order or arguments. 


Plugins 


Authoring Plugins 


For some use cases, it may be necessary to write a plugin that offloads work to 
another system. This is especially useful for things that may not fit in the "standard 
library" of Consul Template, but still need to be shared across multiple instances. 


Consul Template plugins must have the following API: 


$ NAME [INPUT...] 


NAME - the name of the plugin - this is also the name of the binary, either a full 
path or just the program name. It will be executed in a shell with the inherited 
PATH so e.g. the plugin cat will run the first executable cat that is found on the 
PATH. INPUT - input from the template - this will always be JSON if provided 
Important Notes 


Plugins execute user-provided scripts and pass in potentially sensitive data from 
Consul or Vault. Nothing is validated or protected by Consul Template, so all 
necessary precautions and considerations should be made by template authors 
Plugin output must be returned as a string on stdout. Only stdout will be parsed for 
output. Be sure to log all errors, debugging messages onto stderr to avoid errors 
when Consul Template returns the value. Always exit 0 or Consul Template will 
assume the plugin failed to execute Ensure the empty input case is handled 
correctly (see Multi-phase execution) Data piped into the plugin is appended after 
any parameters given explicitly (eg 

{{ "sample-data" | plugin "my-plugin" "some-parameter"}} will call my- 
plugin some-parameter sample-data) Here is a sample plugin in a few different 
languages that removes any JSON keys that start with an underscore and returns 
the JSON string: 


#! /usr/bin/env ruby 
require "json" 


if ARGV.empty? 
puts JSON. fast_generate({}) 
Kernel.exit(0) 

end 


hash = JSON.parse(ARGV. first) 
hash.reject! ( |k, | k.start with?(" ") } 
puts JSON.fast generate(hash) 
Kernel.exit(0) 
func main() { 

arg :- []byte(os.Args[1]) 


var parsed map[string]interface{} 

if err := json.Unmarshal(arg, &parsed); err != nil { 
fmt.Fprintln(os.Stderr, fmt.Sprintf("err: %s", err)) 
os.Exit(1) 


for k, _ := range parsed { 
if string(k[0]) == "_" { 
delete(parsed, k) 
} 


} 


result, err := json.Marshal(parsed) 

if err != nil { 
fmt.Fprintln(os.Stderr, fmt.Sprintf("err: %s", err)) 
os.Exit(1) 

} 


fmt.Fprintln(os.Stdout, fmt.Sprintf("%s", result)) 
os.Exit(0) 


Caveats 


Exec Mode 


As of version 0.16.0, Consul Template has the ability to maintain an arbitrary child 
process (similar to envconsul). This mode is most beneficial when running Consul 
Template in a container or on a scheduler like Nomad or Kubernetes. When 
activated, Consul Template will spawn and manage the lifecycle of the child 
process. 


This mode is best-explained through example. Consider a simple application that 
reads a configuration file from disk and spawns a server from that configuration. 


$ consul-template \ 
-template="/tmp/config.ctmpl:/tmp/server.conf" \ 
-exec="/bin/my-server -config /tmp/server.conf" 


When Consul Template starts, it will pull the required dependencies and populate 
the /tmp/server.conf, which the my-server binary consumes. After that template is 
rendered completely the first time, Consul Template spawns and manages a child 
process. When any of the list templates change, Consul Template will send the 
configurable reload signal to that child process. If no reload signal is provided, 
Consul Template will kill and restart the process. Additionally, in this mode, Consul 
Template will proxy any signals it receives to the child process. This enables a 
scheduler to control the lifecycle of the process and also eases the friction of 
running inside a container. 


A common point of confusion is that the command string behaves the same as the 
shell; it does not. In the shell, when you run foo | bar or foo > bar, that is actually 
running as a subprocess of your shell (bash, zsh, csh, etc.). When Consul 
Template spawns the exec process, it runs outside of your shell. This behavior is 
different from when Consul Template executes the template-specific reload 
command. If you want the ability to pipe or redirect in the exec command, you will 
need to spawn the process in subshell, for example: 


exec { command = "$SHELL -c 'my-server > /var/log/my-server.log™ ) Note that 
when spawning like this, most shells do not proxy signals to their child by default, 
so your child process will not receive the signals that Consul Template sends to 
the shell. You can avoid this by writing a tiny shell wrapper and executing that 
instead: 


l/usr/bin/env bash 


trap "kill -TERM Schild" SIGTERM 


/bin/my-server -config /tmp/server.conf child=$! wait "Schild" Alternatively, you can 
use your shell's exec function directly, if it exists: 


#!/usr/bin/env bash 
exec /bin/my-server -config /tmp/server.conf » /var/log/my-serve 
r.log 


There are some additional caveats with Exec Mode, which should be considered 
carefully before use: 


If the child process dies, the Consul Template process will also die. Consul 
Template does not supervise the process! This is generally the responsibility of 
the scheduler or init system. The child process must remain in the foreground. 
This is a requirement for Consul Template to manage the process and send 


signals. The exec command will only start after all templates have been rendered 
at least once. One may have multiple templates for a single Consul Template 
process, all of which must be rendered before the process starts. Consider 
something like an nginx or apache configuration where both the process 
configuration file and individual site configuration must be written in order for the 
service to successfully start. After the child process is started, any change to any 
dependent template will cause the reload signal to be sent to the child process. 
This reload signal defaults to nil, in which Consul Template will not kill and 
respawn the child. The reload signal can be specified and customized via the CLI 
or configuration file. When Consul Template is stopped gracefully, it will send the 
configurable kill signal to the child process. The default value is SIGTERM, but it 
can be customized via the CLI or configuration file. Consul Template will forward 
all signals it receives to the child process except its defined reload signal, 

dump signal, and kill signal. If you disable these signals, Consul Template will 
forward them to the child process. It is not possible to have more than one exec 
command (although each template can still have its own reload command). 
Individual template reload commands still fire independently of the exec 
command. De-Duplication Mode 


Consul Template works by parsing templates to determine what data is needed 
and then watching Consul for any changes to that data. This allows Consul 
Template to efficiently re-render templates when a change occurs. However, if 
there are many instances of Consul Template rendering a common template there 
is a linear duplication of work as each instance is querying the same data. 


To make this pattern more efficient Consul Template supports work de-duplication 
across instances. This can be enabled with the -dedup flag or via the deduplicate 
configuration block. Once enabled, Consul Template uses leader election on a 
per-template basis to have only a single node perform the queries. Results are 
shared among other instances rendering the same template by passing 
compressed data through the Consul K/V store. 


Please note that no Vault data will be stored in the compressed template. 
Because ACLs around Vault are typically more closely controlled than those ACLs 
around Consul's KV, Consul Template will still request the secret from Vault on 
each iteration. 


Termination on Error 


By default Consul Template is highly fault-tolerant. If Consul is unreachable or a 
template changes, Consul Template will happily continue running. The only 
exception to this rule is if the optional command exits non-zero. In this case, 
Consul Template will also exit non-zero. The reason for this decision is so the user 
can easily configure something like Upstart or God to manage Consul Template as 
a service. 


If you want Consul Template to continue watching for changes, even if the optional 
command argument fails, you can append || true to your command. For example: 


$ consul-template \ 
-template "in.ctmpl:out.file:service nginx restart || true" 


In this example, even if the Nginx restart command returns non-zero, the overall 
function will still return an OK exit code; Consul Template will continue to run as a 
service. Additionally, if you have complex logic for restarting your service, you can 
intelligently choose when you want Consul Template to exit and when you want it 
to continue to watch for changes. For these types of complex scripts, we 
recommend using a custom sh or bash script instead of putting the logic directly in 
the consul-template command or configuration file. 


Command Environment 


The current processes environment is used when executing commands with the 
following additional environment variables: 


CONSUL HTTP ADDR 
CONSUL HTTP TOKEN 
CONSUL HTTP AUTH 
CONSUL HTTP SSL 
CONSUL HTTP SSL VERIFY 


These environment variables are exported with their current values when the 
command executes. Other Consul tooling reads these environment variables, 
providing smooth integration with other Consul tools (like consul maint or consul 
lock). Additionally, exposing these environment variables gives power users the 
ability to further customize their command script. 


Multi-phase Execution 


Consul Template does an n-pass evaluation of templates, accumulating 
dependencies on each pass. This is required due to nested dependencies, such 
as: 


{{range services)? 

{{range service .Name}} 
{{.Address}} 

{fend} }{{end}} 


During the first pass, Consul Template does not know any of the services in 
Consul, so it has to perform a query. When those results are returned, the inner- 
loop is then evaluated with that result, potentially creating more queries and 
watches. 


Because of this implementation, template functions need a default value that is an 
acceptable parameter to a range function (or similar), but does not actually 
execute the inner loop (which would cause a panic). This is important to mention 
because complex templates must account for the "empty" case. For example, the 
following will not work: 


{{with index (service "foo") 03) 
Ho 
{{end}} 


This will raise an error like: 


: error calling index: index out of range: 0 That is because, during the first 
evaluation of the template, the service key is returning an empty slice. You can 
account for this in your template like so: 


{{if service "foo"}} 

{{with index (service "foo") 03) 
{{. Node} } 

{{ end }} 

{{ end }} 


This will still add the dependency to the list of watches, but Go will not evaluate 
the inner-if, avoiding the out-of-index error. 


Examples 


HAProxy 


HAProxy is a very common load balancer. You can read more about the HAProxy 
configuration file syntax in the HAProxy documentation, but here is an example 
template for rendering an HAProxy configuration file with Consul Template: 


global 
daemon 
maxconn {{key "service/haproxy/maxconn"}} 


defaults 

mode {{key "service/haproxy/mode"}}{{range ls "service/hapro 
xy/timeouts"}} 

timeout {{.Key}} {{.Value}}{{end}} 


listen http-in 
bind *:8000{{range service "release.web"}} 
server {{.Node}} {{.Address}}:{{.Port}}{{end}} 


Save this file to disk as haproxy.ctmpl and run the consul-template daemon: 


$ consul-template \ 
-consul demo.consul.io \ 
-template haproxy.ctmpl:/etc/haproxy/haproxy.conf 
-dry 


Depending on the state of the demo Consul instance, you could see the following 
output: 


global 
daemon 
maxconn 4 


defaults 
mode default 
timeout 5 


listen http-in 
bind *:8000 
server nyc3-worker-2 104.131.109.224:80 
server nyc3-worker-3 104.131.59.59:80 
server nyc3-worker-1 104.131.86.92:80 


For more information on how to save this result to disk or for the full list of 
functionality available inside a Consul template file, please consult the API 
documentation. 


Varnish 


Varnish is an common caching engine that can also act as a proxy. You can read 
more about the Varnish configuration file syntax in the Varnish documentation, but 
here is an example template for rendering a Varnish configuration file with Consul 
Template: 


import directors; 
{{range service "consul"}} 
backend {{.Name}}_{{.ID}} { 


.host = "{{.Address}}"; 
port = "{{.Port}}"; 
}{{end}} 


sub vcl init { 

new bar - directors.round robin(); 
{{range service "consul"? 

bar.add backend(((.Name)3 {{.1ID}});{{end}} 
j 


sub vcl recv ( 
set req.backend hint - bar.backend(); 


j 


Save this file to disk as varnish.ctmpl and run the consul-template daemon: 


$ consul-template \ 
-consul demo.consul.io \ 
-template varnish.ctmpl:/etc/varnish/varnish.conf \ 
-dry 


You should see the following output: 


import directors; 


backend consul_consul { 
.host = "104.131.109.106"; 
,port = "8300";" 

} 


sub vcl init { 
new bar - directors.round robin(); 


bar.add backend(consul consul); 


} 


sub vcl_recv { 
set req.backend hint = bar.backend(); 


} 


Apache httpd 


Apache httpd is a popular web server. You can read more about the Apache httpd 
configuration file syntax in the Apache httpd documentation, but here is an 
example template for rendering part of an Apache httpd configuration file that is 
responsible for configuring a reverse proxy with dynamic end points based on 
service tags with Consul Template: 


{{range $tag, $service := service "web" | byTag}} 

# "{{$tag}}" api providers. 

<Proxy balancer://{{$tag}}> 

{{range $service}} BalancerMember http://{{.Address}}:{{.Port}} 
{{end}} ProxySet lbmethod-bybusyness 

</Proxy> 

Redirect permanent /api/{{$tag}} /api/{{$tag}}/ 

ProxyPass /api/{{$tag}}/ balancer://{{$tag}}/ 

ProxyPassReverse /api/{{$tag}}/ balancer://{{$tag}}/ 

{fend }} 


Just like the previous examples, save this file to disk and run the consul-template 
daemon: 


$ consul-template \ 
-consul demo.consul.io \ 
-template httpd.ctmpl:/etc/httpd/sites-available/balancer.conf 


You should see output similar to the following: 


# "frontend" api providers. 

<Proxy balancer://frontend> 
BalancerMember http://104.131.109.106:8080 
BalancerMember http://104.131.109.113:8081 
ProxySet lbmethod-bybusyness 

</Proxy> 

Redirect permanent /api/frontend /api/frontend/ 

ProxyPass /api/frontend/ balancer://frontend/ 

ProxyPassReverse /api/frontend/ balancer://frontend/ 


# "api" api providers. 
<Proxy balancer://api> 
BalancerMember http://104.131.108.11:8500 
ProxySet lbmethod-bybusyness 
</Proxy> 
Redirect permanent /api/api /api/api/ 
ProxyPass /api/api/ balancer://api/ 
ProxyPassReverse /api/api/ balancer://api/ 


Querying all services 


As of Consul Template 0.6.0, it is possible to have a complex dependency graph 
with dependent services. As such, it is possible to query and watch all services in 
Consul: 


{{range services}}# {{.Name}}{{range service .Name}} 


{{.Address}}{{end}} 
{{end}} 


Just like the previous examples, save this file to disk and run the consul-template 
daemon: 


$ consul-template \ 
-consul demo.consul.io \ 
-template everything.ctmpl:/tmp/inventory 


You should see output similar to the following: 


# consul 
104.131.121.232 


# redis 
104.131.86.92 
104.131.109.224 
104.131.59.59 


# web 
104.131.86.92 
104.131.109.224 
104.131.59.59 


Running and Process Lifecycle 


While there are multiple ways to run Consul Template, the most common pattern 
is to run Consul Template as a system service. When Consul Template first starts, 
it reads any configuration files and templates from disk and loads them into 
memory. From that point forward, changes to the files on disk do not propagate to 
running process without a reload. 


The reason for this behavior is simple and aligns with other tools like haproxy. A 
user may want to perform pre-flight validation checks on the configuration or 
templates before loading them into the process. Additionally, a user may want to 
update configuration and templates simultaneously. Having Consul Template 
automatically watch and reload those files on changes is both operationally 
dangerous and against some of the paradigms of modern infrastructure. Instead, 
Consul Template listens for the SIGHUP syscall to trigger a configuration reload. If 


you update configuration or templates, simply send HUP to the running Consul 
Template process and Consul Template will reload all the configurations and 
templates from disk. 


Debugging 


Consul Template can print verbose debugging output. To set the log level for 
Consul Template, use the -log-level flag: 


$ consul-template -log-level info ... 

«timestamp» [INFO] (cli) received redis from Watcher 
«timestamp» [INFO] (cli) invoking Runner 

Hope 


You can also specify the level as debug: 


$ consul-template -log-level debug ... 

«timestamp» [DEBUG] (cli) creating Runner 

«timestamp» [DEBUG] (cli) creating Consul API client 
«timestamp» [DEBUG] (cli) creating Watcher 

«timestamp» [DEBUG] (cli) looping for data 

«timestamp» [DEBUG] (watcher) starting watch 

«timestamp» [DEBUG] (watcher) all pollers have started, waiting 
for finish 

«timestamp» [DEBUG] (redis) starting poll 

«timestamp» [DEBUG] (service redis) querying Consul with &{...} 
«timestamp» [DEBUG] (service redis) Consul returned 2 services 
«timestamp» [DEBUG] (redis) writing data to channel 

«timestamp» [DEBUG] (redis) starting poll 

«timestamp» [INFO] (cli) received redis from Watcher 
«timestamp» [INFO] (cli) invoking Runner 

«timestamp» [DEBUG] (service redis) querying Consul with &{...} 
Ho e 


FAQ 


Q: How is this different than confd? 


A: The answer is simple: Service Discovery as a first class citizen. You are also 
encouraged to read this Pull Request on the project for more background 
information. We think confd is a great project, but Consul Template fills a missing 
gap. Additionally, Consul Template has first class integration with Vault, making it 
easy to incorporate secret material like database credentials or API tokens into 
configuration files. 


Q: How is this different than Puppet/Chef/Ansible/Salt? 


A: Configuration management tools are designed to be used in unison with Consul 
Template. Instead of rendering a stale configuration file, use your configuration 
management software to render a dynamic template that will be populated by 
Consul. 


Contributing 


To build and install Consul Template locally, you will need a modern Go (Go 1.57) 
environment. 


First, clone the repo: 


$ git clone https://github.com/hashicorp/consul-template.git 


Next, download/update all the dependencies: 


$ make updatedeps 


To compile the consul-template binary and run the test suite: 


$ make dev 


This will compile the consul-template binary into bin/consul-template as well as 
your $GOPATH and run the test suite. 


If you just want to run the tests: 


$ make test 


Or to run a specific test in the suite: 


go test ./... -run SomeTestFunction name 


Submit Pull Requests and Issues to the Consul Template project on GitHub. 


